GRPPHA (July94) ftools.heasarc GRPPHA (July94) NAME grppha -- Manipulates OGIP standard PHA FITS file USAGE grppha infile outfile DESCRIPTION GRPPHA is an interactive command driven task to define (or redefine) and/or display the grouping (binning) & quality flags, and the fractional systematic errors associated with channels in a FITS PHA file. A new FITS PHA file can be written at any time which includes the latest settings of the above, along with a copy of any other extensions in the original file. The various commands and their syntax are described in the command summary below. It should be noted that none of the commands available within this task change the actual PHA dataset itself (ie the observed counts vs channel histogram) in any way. Instead the necessary grouping, quality & systematic error information for each channel is written alongside the PHA dataset to be picked up by subsequent GRPPHA commands and downstream software (eg XSPEC). On entry, the task displays the values of the keywords mandatory for FITS PHA extension conforming to an OGIP standard format. The user is then repeatedly prompted for commands until they exit (or quit) the task. This grppha help file is based on the OGIP Calibration Memo CAL/SW/93-010 available on line at http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/ cal_sw_93_010/cal_sw_93_010.html and in the OGIP anonymous FTP account on legacy.gsfc.nasa.gov (Internet: 128.183.8.233) as caldb/docs/memos/cal_sw_93_010.tex. COMMAND SUMMARY There are 7 "families" of command strings currently implemented: 1) group - to group (or rebin) channels 2) bad - to set channels to bad quality (ignored by XSPEC etc) 3) good - to (re)set channels to good quality 4) systematics - to set the fractional systematic error of the data 5) show - to display the current settings to the terminal 6) reset - to remove any current settings 7) chkey - to change keyword value The following commands are also available: 8) write - to write a new PHA file with the current settings 9) exit - to exit the task (writing a new file) 10)quit - to quit the task 11)help - interactive help Several commands can be specified on the command line by separating them with an ampersand '&' The various capabilities, limitations & syntax of each of the above are as follows: 1) GROUP (or group) Sets the grouping flags such that the PHA dataset can be rebinned. It is stressed that the group command does NOT change the observed counts vs PHA channel dataset in any way. Rather this command fills the GROUPING column with appropriate flags to delineate which channels start each new 'bin' (value = +1), and which are part of a continuing 'bin' (-1). There are 3 methods by which the grouping can be set: GRPPHA> GROUP MINCHAN MAXCHAN NCHAN The data is grouped from MINCHAN to MAXCHAN (inclusive) with NCHAN bins in each group. Any 'spare' channels will be left ungrouped and the user informed. Any grouping requested which partially overlaps a a pre-existing grouping will also be ignored and the user informed. A maximum of 6 sets of groupings is allowed on the command line. eg: group 10 20 2 21 30 10 will set the grouping flag such that from channel 10 to channel 19 the data can be binned up by a factor 2, channel 20 is "spare" and left unbinned, and channels 21 to 30 can form a single bin. GRPPHA> GROUP GRP_FILE.DAT The grouping information is read (free-format) from the data file "GRP_FILE.DAT". This file is in ASCII format and can consist of up to 100 lines (sets of groupings, one per line) with the syntax MINCHAN MAXCHAN NCHAN, where these have the same meanings as above. The rules regarding spare and overlapping groupings are as above GRPPHA> GROUP MIN RCNTS The grouping is set such that each new grouping contains a minimum of RCNTS counts in each bin. Channels that are defined as BAD are not included. Any spare channels at the end of the data are defined BAD by software (QUALITY=2). 2) BAD (or bad) Sets the quality flags such that the specified channels can be ignored by certain subsequent commands (such as GROUP MIN RCNTS above) and downstream software (eg XSPEC). The quality flags of unspecified channels are unchanged. There are 2 methods whereby channels can be set bad: GRPPHA> BAD MINCHAN-MAXCHAN Channels between MINCHAN and MAXCHAN (inclusive) are set bad (Quality = 5). Note the hyphen: should this not be present, the task will set MINCHAN and MAXCHAN (only) to bad, leaving all channels in between with their previous quality flags. A maximum of 6 sets of channels are allowed on the command line. eg: bad 1 5-20 29 100 will set the quality flag such that channels 1, 5 through 20, 29 and 100 are defined to be bad. GRPPHA> BAD BADFILE.DAT The quality information is read (free-format) from the data file "BADFILE.DAT". This file is in ASCII format and can consist of up to 100 lines (sets of channel ranges, one per line) with the syntax MINCHAN MAXCHAN where these have the same meanings as above. NOTE: Unlike the command line, hyphens are illegal syntax in the file, and single channels which are to be set bad must be specified setting MAXCHAN to MINCHAN explicitly. 3) GOOD (or good) Sets the quality flags such that the specified channels are considered good (Quality = 0). The quality flags of unspecified channels are unchanged. There are 2 methods whereby channels can be set good: GRPPHA> GOOD MINCHAN-MAXCHAN Channels between MINCHAN and MAXCHAN (inclusive) are set good should they not be so already. As in the case of the BAD command, note the use of the hyphen - should this not be present, the task will set MINCHAN and MAXCHAN (only) to good, leaving all channels in between with their previous quality flags. A maximum of 6 sets of channels are allowed on the command line. eg: good 2 6-18 99 will set the quality flag such that channels 2, 6 through 18 and 99 are defined to be good. GRPPHA> GOOD GOODFILE.DAT The quality information is read (free-format) from the data file "GOODFILE.DAT". This file is in ASCII format and can consist of up to 100 lines (sets of channel ranges, one per line) with the syntax MINCHAN MAXCHAN where these have the same meanings as above. NOTE: Unlike the command line, hyphens are illegal syntax in the file, and single channels which are to be set good must be specified setting MAXCHAN to MINCHAN explicitly. 4) SYSTEMATICS (or systematics) Sets the fractional systematic error for each PHA channel which should be combined with the corresponding statistical error on the data to define the true (total) error on the data. It is stressed that this command obviously does NOT change the observed (statistical) error associated with the PHA data. Rather SYS_ERR column is filled with the appropriate values, and the command is therefore reversible. There are 2 methods whereby the systematic errors can be set: GRPPHA> SYSTEMATICS MINCHAN-MAXCHAN ERR Channels between MINCHAN and MAXCHAN (inclusive) will have a fractional systematic error of ERR defined (ERR = 0.03 corresponds to a systematic error of 3% of the observed PHA count rate for that channel). A maximum of 6 errors are permitted on the command line. GRPPHA> SYSTEMATICS SYSFILE.DAT The information regarding the fractional systematic errors is read (free-format) from the data file "SYSFILE.DAT". This file is in ASCII format and can consist of up to 100 lines (sets of channel ranges, one per line) with the syntax MINCHAN MAXCHAN ERR where these have the same meanings as above. 5) SHOW (or show) Displays the current settings to the screen in a concise format. GRPPHA> SHOW GROUPING Displays the current channel GROUPING cards to the screen. GRPPHA> SHOW QUALITY Displays current QUALITY flags to the screen. GRPPHA> SHOW SYSTEMATICS Displays current fractional SYSTEMATIC errors to the screen. GRPPHA> SHOW ALL Displays the current channel GROUPING cards, QUALITY flags and fractional SYSTEMATIC errors to the screen. GRPPHA> SHOW KEYWORDS Displays mandatory PHA keywords, and their current values. GRPPHA> SHOW INFILE Displays input filename. GRPPHA> SHOW CHKEYS Displays names of keywords that can have their values changed. In addition any of the CHKEY keywords can be displayed in full. An example is SHOW RESPFILE. 6) RESET (or reset) Resets the current settings to 'null', NOT to those in the original input file. GRPPHA> RESET GROUPING Reset all the channel GROUPING flags to 1, that is to unbinned. NOTE: The grouping is not reset to that of the original file. GRPPHA> RESET QUALITY Reset all the channel QUALITY flags to good (Qual = 0), regardless of the original setting. GRPPHA> RESET SYSTEMATICS Reset the fractional SYSTEMATIC errors to zero. GRPPHA> RESET ALL Reset all the channel GROUPING card, QUALITY flags and fractional SYSTEMATIC errors. 7) CHKEY (or chkey) This command allows a keyword value to be changed. Users are permitted to change the values of a subsection of the mandatory keywords. GRPPHA>CHKEY KEYWORD NEWVALUE The value of KEYWORD is changed to NEWVALUE. NOTE : The maximum allowed length for a number is 20, and for a character string (for filenames) is 120. An example, is CHKEY AREASCAL 1.03. 8) WRITE Writes an output file. GRPPHA> WRITE ABCD.PHA Writes a new PHA file called "ABCD.PHA" with the current settings, and including copies of any other extensions present within the original input PHA file. This command does not stop the task, thus settings can be altered further and subsequently written to another file. GRPPHA> WRITE !ABCD.PHA Writes a new PHA file called "ABCD.PHA" with the current setting, the ! indicates that if ABCD.PHA already exists it is OVERWRITTEN. 9) EXIT Exits the task. GRPPHA> EXIT Exit the task, first writing a new PHA file with the name as specified by the input parameter outfile (default "GRPPHA.OUT") with the final settings, and including copies of any other extensions present within the original input PHA file. GRPPHA> EXIT !ABCD.PHA Exit the task, first writing a new PHA file, the ! indicates that if ABCD.PHA already exists, it is OVERWRITTEN. This filename overrides the input parameter outfile. 10) QUIT Quits from the task GRPPHA> QUIT Exit the task without writing a new PHA file. 11) HELP Interactive help, lists available commands. "?" or "commands" will also give this help. For interactive help for a particular command, "HELP COMMAND" will give a description, and the syntax, for example "HELP GROUP" describes the grouping facility. WARNINGS ON USAGE When the grouping command, "group MINCHAN MAXCHAN NCHAN" is used if an overlap occurs with a previous setting, the data is rebinned after the overlap if applicable. If the user wants to overwrite the original setting the reset command should be used. Note : The "group min" command does not check for any overlaps. When using files with the bad and good commands, filenames with hyphens are not permitted. The CHKEY command has been updated to allow a maximum string length of 120. In order to do this a fitsio continuation convention is used. NOTE: This may cause problems if downstream software has not been appropriately modified. PARAMETERS infile [character] The input filename containing the PHA data in OGIP standard, as a BINARY table FITS extension outfile [character] The name of the output file to be created (in OGIP standard format). The default output file is GRPPHA.OUT comm [character] The command string at the first prompt. tempc [character] The command string starting from the second prompt. chatter [integer] The value of the chatter flag, useful for reassurance & diagnostics purposes. The default value is chatter=5, with chatter <= 5 being very quite and chatter >= 20 very verbose. (clobber = false) [boolean] Flag specifying whether or not a pre-existing file with the same name as that requested as the output file from this task will be overwritten. EXAMPLES 1) To manipulate the PHA file "my_file.pha" , and write to "my_file.grp" with the changes if any, and default chattiness : he> grppha my_file.pha myfile.grp Now the PHA extension mandatory keywords, and values will be displayed on the screen. The GRPPHA prompt will appear. An example command is "group MINCHAN MAXCHAN NCHAN ", the data would be rebinned from MINCHAN to MAXCHAN with NCHAN specifying the number of bins to be grouped : grppha> group 1 400 10 This command will group 1 to 400 with 10 bins in each group. To show the current grouping : grppha> show grouping EXIT can be used to write a new file with the rebinned data. Note : in addition to the SPECTRUM extension, all other extensions in the input file are copied : grppha> exit 2) To use "test.pha" as input PHA file, and use the default output file, with default chattiness (quiet) : he> grppha test.pha To add a systematic error to channels 40 to 56 : grppha> systematics 40-56 0.03 A 3% systematic error is added. Now to set bad channels, that is these channels will be ignored in XSPEC : grppha> bad 11 20-40 This command sets channel 11 to bad, and channels 20 to 40 bad inclusively. In order to see the current grouping, systematic errors, and quality settings : grppha> show all To exit the program without writing to a file : grppha> quit 3) To use "bbxrt.pha" as input file, and "bbxrt.grp",as output filename, with verbose chattiness : he> grppha bbxrt.pha bbxrt.grp 20 To group the data with at least 30 raw counts in each bin : grppha> group min 30 The current changes can be written to a file, without exiting grppha : grppha> write bbxrt30.grp The reset command can be used to set all the data as unbinned. After this the data can be rebinned afresh. To reset : grppha> reset grouping To set bad channels by defining them in a file : grppha> bad badfile.dat To exit, and write a new PHA file : grppha> exit BUGS None known SEE ALSO Chanpha (xspec) Legacy No.2 cal/sw/93-010 LOG OF SIGNIFICANT CHANGES v1.0.9 (1994 Jan) GRPPHA can be run in non-interactive mode by separating commands with an ampersand "&". It is now spawned by Xselect. image v1.0.0 (1993 March) Initial public release PRIMARY AUTHOR Rehana Yusaf HEASARC NASA/GSFC http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp (301) 286-6115