NAME

USAGE

DESCRIPTION

The xamkregion task creates special region files showing the field of view of each of the XRISM instruments in each of the standard coordinate systems described in the telescope definition (teldef) calibration files. The standard coordinate systems are referred to as ACT (ACTive), DET (DETector), FOC (FOCal plane), and SKY. The task either starts with a seed input region, which must be in ACT coordinates (specified by the parameter 'inregion'), or it generates a seed region in ACT coordinates. In the case of Xtend, the internally-generated seed region is a simple box corresponding to the perimeter of the detector, whose sides are parallel to one of the coordinate axes. In the case of Resolve, the the internally-generated seed region consists of up to 35 individual perfect squares (corresponding to 35 pixels). These squares have a side length of 0.832 mm, are centered on the average of measurements of the four corner coordinates of a given pixel, and rotated by a small angle that gives the best representation of the corner measurments. The task uses the teldef file to calculate the internally-generated region parameters on-the-fly. Currently, the teldef file is only used to convert the seed region in ACT coordinates to regions in the other coordinate systems.

The xamkregion task creates region files for a single instrument, Resolve or Xtend, or one region file containing the field of view of all instruments. Note that the individual region files for both Resolve and Xtend are also retained when xamkregion is executed for all instruments ('instrume=ALL'). These region files may be used for event filtering, or in programs such as ds9 or ximage. The xamkregion task also creates region files containing labels for the instrument and instrument segments (e.g., CCD units for Xtend), and a script for reading the region files into ximage.

Note that Resolve region files made by xamkregion should not be used as input to the ARF generator tools, xaarfgen and xaxmaarfgen. This is because xamkregion creates DET coordinate regions for Resolve that have overlapping pixel regions.

PARAMETERS

instrume = RESOLVE [string RESOLVE|XTEND]

Name of instrument to be used. If set to a single instrument, only the region files for that instrument are created. When 'instrume=ALL', the xamkregion task creates individual instrument region files that are concatenated to make a unified region file; the individual instrument region files are retained for future use.

ra = 50 [double]

The right ascension [decimal degrees] of the nominal pointing. This must be within the range 0 <= ra <= 360 degrees.

dec = 50 [double]

The declination [decimal degrees] of the nominal pointing. This must be within the range -90 <= dec <= +90 degrees.

roll = 90 [double]

The roll angle [decimal degrees] between the SKY and FOC coordinate systems. The roll angle is defined to correspond to a rotation about the center of the SKY system and is measured counterclockwise from the positive SKY Y axis to the positive FOC Y axis.

(teldeffile = CALDB) [string CALDB|file name]

Name of the teldef calibration file, which specifies the coordinate systems and transformation properties. If the parameter is set to CALDB, the file is read from the calibration database, CalDB. If a file name is provided, the INSTRUME keyword in the file must match exactly the value of the 'instrume' parameter. Note: if 'instrume=ALL', then the only acceptable value for 'teldeffile' is CALDB, since multiple teldef files are read. Note, the 'teldeffile' is reset to CALDB internally in the case a user enters a file name instead of CALDB when 'instrume=ALL'.

(inregion = NONE) [string]

If 'inregion=NONE', xamkregion starts from an internally-generated seed region in ACT coordinates, appropriate for the selected instrument. If the 'inregion' parameter is not NONE, the seed region provided by the user must be in ACT coordinates and specified by the user as a file name. If 'instrume=ALL', NONE is the only acceptable value for 'inregion' and it will be reset internally to NONE if the user has provided a file name.

(outroot = NONE) [string]

If 'outroot=NONE', the names for the output region files are INST.SYS.box.reg, where INST is the instrument name and SYS is the three-letter coordinate system name. If 'outroot' is not NONE, then 'INST' is replaced by user input value of the 'outroot' parameter.

(pixlist = 0-35) [string]

List of Resolve pixels to be included in the output region files. This is a comma-separated list for which the user can specify either single pixel numbers or a range of pixel numbers. This parameter is ignored if the 'instrume' parameter is not set to Resolve.

(outtextregion = yes) [boolean yes|no]

By default, xamkregion outputs two sets of region files: simple box-style regions with no text labels (INST.SYS.box.reg) and box-style regions with text labels (INST.SYS.text.reg). However, if 'outtextregion=no', then xamkregion does not make the set of regions that include text labels.

(outxco = yes) [boolean yes|no]

By default, xamkregion creates several command scripts (INST.SYS.xco) for reading the region files into the program ximage. However, if 'outxco=no', these scripts are not created.

(cleanup = yes) [boolean yes|no]

Delete temporary files.

(clobber = yes) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 2) [integer 0|1|2|3]

Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]

Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records task parameters in HISTORY.

EXAMPLES

1. Run xamkregion for the XRISM Xtend instrument.

   xamkregion instrume=XTEND ra=185.0 dec=-42.1 roll=35.0 teldeffile=CALDB

2. Run xamkregion with 'instrume=ALL' and switch off the creation of text region files and xco scripts.

   xamkregion instrume=ALL ra=185.0 dec=-42.1 roll=35.0 outtextregion=no outxco=no

3. Run xamkregion with 'instrume=RESOLVE' and a range of pixel values. In this example, the user chooses pixel 0, pixel 2, and pixels 4, 5, 6, and 7.

   xamkregion instrume=RESOLVE ra=25.0 dec=-42.1 roll=35.0 pixlist="0,2,4-7"

SEE ALSO

LAST MODIFIED

August 14, 2023