NAME

USAGE

DESCRIPTION

Create a merged output event file from a list of input event files (such as HEALPixel files), selecting only events in the input files that fall within a given radius of a sky location. Optionally, a column may be selected (such as "CCDID") to make multiple output event files, one for each value in the selected column. Optionally, specified keywords and/or columns in the input event files can be excluded by the output file(s).

PARAMETERS

evtlist [filename]

A list of input event files to be merged. This may be a comma-delimited list of files, or the name of a text file containing a list of files, one per line, preceded by an '@' character.

outfstem [string]

Output file rootname. If no 'cameracol' set, the output will be a single event file "outfstem.evt". If 'cameracol' is set, the output will be a set of files named "outfstem#.evt" where "#" indicates which value of 'cameracol' the events match.

object [string]

String value for the OBJECT keyword to set in the output event file(s).

ra [real] (J2000; degrees]

Right Ascension of sky position at the center of the output projection plane.

dec [real] (J2000; degrees)

Declination of the sky position at the center of the output projection plane.

radius [real] (degrees

Radius around the specified sky position to be included in the output event file(s). Events outside this radius are exluded from the output file(s).

(cameracol = "NONE") [string]

Separate events into multiple output event files, one of each value found in 'cameracol'. Ignored if set to "NONE" (default).

(coldellist = "NONE") [string]

List of columns to be excluded from the output event file(s). This may be a comma-delimited list of columns, or the name of a text file containing a list of columns, one per line, preceded by an '@' character. Ignored if set to "NONE" (default).

(keydellist = "NONE") [string]

List of keywords to be excluded from the output event file(s). This may be a comma-delimited list of keywards, or the name of a text file containing a list of keywords, one per line, preceded by an '@' character. Ignored if set to "NONE" (default).

(leapsecfile = "REFDATA") [filename]

Name of the leap second file. If set to "REFDATA" (default), the leap second file in the directory set by the REFDATA environment setting will be used.

(nx = -99) [integer]

The number of pixels in the x-direction to include in the X column. If set to a negative value (default), the value of 'nx' is set to match the input event files or 2 x 'radius' / 'pixsize', whichever is larger.

(ny = -99) [integer]

The number of pixels in the y-direction to include in the Y column. If set to a negative value (default), the value of 'ny' is set to match the input event files or 2 x 'radius' / 'pixsize', whichever is larger.

(pixsize = -99) [real] (degrees)

The size of the pixels in degrees. If set to a negative number (default), the output pixel size is identical to the input event files.

(cleanup = no) [boolean]

Determines whether to delete temporary files. When set to no (default), intermediate files will be retained. NOTE: this feature is not implimented in this tool.

(clobber = no) [boolean]

Overwrites any existing output file(s) if set to yes. Default is no.

(chatter = 1) [integer]

Sets the amount of output from the code. Values range from 0 (little to no output) to 3 (verbose: provides considerable output). Default value of 1 provides basic details as the code runs.

(logfile = "!DEFAULT") [string]

Record output from running this tool in a logfile. If set to DEFAULT, the output logfile will be named hpextract.log. If preceded by the "!", any existing file with the same name will be overwritten; otherwise this output will be appended to any existing file. No log file made if set to "NONE" (or blank). Default setting is "!DEFAULT".

(history = yes) [boolean]

Records tool parameters in HISTORY keywords if set to yes (default).

(debug = no) [boolean]

If set to "yes", the code will provide detailed logging of variables and settings. This can be useful when debugging features in the code or deciphering unexpected error conditions. Default is "no".

(mode = ql) [string ql|hl|q]

Mode to query the parameter file. Acceptable values include: "ql" (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).

EXAMPLES

Read a set of MAXI GSC HEALPixel event files, separated by values found in the CAMERAID column. Output files will be named "crab_g0.evt..crab_gb.evt" (for GSC cameras 0-9, "a", and "b"). The new event files contain all events in the listed files in "crab_gsc_tiles.list" which are within 8.0 degrees of the sky position ra=83.633083, dec=22.0145: output files are only made for cameras found with at least one event within this radius. Set the keyword OBJECT in output files to "Crab". Place event X and Y in a 200 x 200 grid with square pixels 0.1 deg wide in a tangent plane projection centered on ra and dec. Record the input parameters for this tool in HISTORY keywords. The output files will not include the keyword EXPOSURE nor the columns COLPHI, DEL_CTHA, and DEL_CPHI. Pre-existing files with the same name as the output files will be replaced.
Note that although event files have been separated based on values in the CAMERAID column, each output file still contains that column. A log file named hpextract.log will be made (default), clobbering any previous log file with the same name.

hpextract @crab_gsc_tiles.list crab_g Crab 83.633083 22.0145 8.0 cameracol=CAMERAID \
  nx=200 ny=200 pixsize=0.1 coldellist="COLPHI,DEL_CTHA,DEL_CPHI" keydellist="EXPOSURE" \
  clobber=yes chatter=1 history=yes

Extract a set of MAXI SSC event files for the SSCH camera from a list of HEALPixel files. Makes a single output event file named "crab_sh.evt". Events are included if they are within 8.0 degrees of the input sky coordinate with nx, ny, and pixsize all copied from the source event files. No history or log file is created. The columns COLPHI, DEL_CTHA, DEL_CPHI, SUN_CTH, SUN_CPH, MON_CTH, MON_CPH, and MOON_PHS are all removed. Chatter is set to maximum (3) for more output to the terminal, but no logfile is recorded.

hpextract @crab_ssch_tiles.list crab_sh Crab 83.633083 22.0145 8.0 \
 coldellist="COLPHI,DEL_CTHA,DEL_CPHI,SUN_CTH,SUN_CPH,MON_CTH,MON_CPH,MOON_PHS" \
 clobber=yes chatter=3 history=no logfile=NONE

SEE ALSO

CAVEATS

1. The columns RA, DEC, X, Y, and TIME are required to be present.
2. The input event files are presumed to be in celestial coordinates in RADECSYS FK5 (J2000). A future version of this code might support additional standard coordinate systems.
3. The event file format is consistent amongst all input files.
4. There must be either an MJDREF keyword or MJDREFI and MJDREFF keyword pair present.
5. Any extensions in the original event file files other than EVENTS will NOT copied: This may be addressed in a future version.
6. The code ONLY reprojects the coordinate system in the X and Y columns. If there are additional columns containing projection-dependent settings (e.g. theta and phi angles), these should be updated elsewhere or discarded.

LAST MODIFIED