.Help grppha July94 ftools.heasarc 
.ih
NAME
grppha -- Manipulates OGIP standard PHA FITS file
.ih
USAGE
grppha infile outfile 
.ih
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
.br
.ce
legacy.gsfc.nasa.gov (Internet: 128.183.8.233)
.br
.nj 
as caldb/docs/memos/cal_sw_93_010.tex.
.ju

.ih
COMMAND SUMMARY

There are 7 "families" of command strings currently implemented:

.br
.nj 
1) group       - to group (or rebin) channels
.br 
.nj
2) bad         - to set channels to bad quality (ignored by XSPEC etc)
.br 
.nj
3) good        - to (re)set channels to good quality
.br 
.nj
4) systematics - to set the fractional systematic error of the data
.br 
.nj
5) show        - to display the current settings to the terminal
.br 
.nj
6) reset       - to remove any current settings
.br 
.nj
7) chkey       - to change keyword value
.br
.nj
.sp
The following commands are also available:
.br 
.nj
8) write       - to write a new PHA file with the current settings 
.br 
.nj
9) exit        - to exit the task (writing a new file)
.br 
.nj
10)quit        - to quit the task
.br
.nj
11)help        - interactive help 
.ju

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:
.br

1) GROUP (or group)
.br
.in 5
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
.br
.in 5
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. 
.br
.sp
.in 3
eg: group 10 20 2 21 30 10 
.br 
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. 

.in -8
GRPPHA> GROUP GRP_FILE.DAT
.br
.in 5
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

.in -5 
GRPPHA> GROUP MIN RCNTS 
.br 
.in 5
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).
.in -10
 
2) BAD (or bad)
.br
.in 5
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
.br
.in 5
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.
.br
.sp
.in 3
eg: bad 1 5-20 29 100      
.br
will set the quality flag such that channels 1, 5 through 20, 29 and 100 are 
defined to be bad.
.in -8 

GRPPHA> BAD BADFILE.DAT 
.br
.in 5
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.

.in -10
3) GOOD (or good)
.br
.in 5
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 
.br
.in 5
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.
.br
.sp
.in 3
eg: good 2 6-18 99         
.br
will set the quality flag such that channels 2, 6 through 18 and 99 are 
defined to be good.

.in -8
GRPPHA> GOOD GOODFILE.DAT
.br
.in 5
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.

.in -10
4) SYSTEMATICS (or systematics)
.br 
.in 5
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
.br
.in 5
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.

.in -5
GRPPHA> SYSTEMATICS SYSFILE.DAT
.br
.in 5
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. 

.in -10
5) SHOW (or show)
.br 
.in 5
Displays the current settings to the screen in a concise format.

GRPPHA> SHOW GROUPING 
.br
.in 5
Displays the current channel GROUPING cards to the screen.

.in -5
GRPPHA> SHOW QUALITY 
.br
.in 5
Displays current QUALITY flags to the screen.

.in -5 
GRPPHA> SHOW SYSTEMATICS  
.br
.in 5
Displays current fractional SYSTEMATIC errors to the screen.

.in -5
GRPPHA> SHOW ALL   
.br 
.in 5
Displays the current channel GROUPING cards, QUALITY flags and fractional 
SYSTEMATIC errors to the screen.

.in -5
GRPPHA> SHOW KEYWORDS
.br
.in 5
Displays mandatory PHA keywords, and their current values.

.in -5
GRPPHA> SHOW INFILE
.br
.in 5
Displays input filename.

.in -5
GRPPHA> SHOW CHKEYS
.br
.in 5
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.


.in -10
6) RESET (or reset)
.br
.in 5
Resets the current settings to 'null', NOT to those in the original input 
file.

GRPPHA> RESET GROUPING
.br
.in 5
Reset all the channel GROUPING flags to 1, that is to unbinned. 
NOTE: The grouping is not reset to that of the original file.

.in -5
GRPPHA> RESET QUALITY 
.br 
.in 5
Reset all the channel QUALITY flags to good (Qual = 0), regardless of
the original setting.

.in -5
GRPPHA> RESET SYSTEMATICS
.br
.in 5
Reset the fractional SYSTEMATIC errors to zero.

.in -5
GRPPHA> RESET ALL   
.br
.in 5
Reset all the channel GROUPING card, QUALITY flags and fractional 
SYSTEMATIC errors.

.in -10
7) CHKEY (or chkey)
.br
.in 5
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
.br
.in 5 

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.

.in -10 
8) WRITE 
.br
.in 5
Writes an output file.

GRPPHA> WRITE ABCD.PHA
.br
.in 5
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.

.in -5
GRPPHA> WRITE !ABCD.PHA
.br
.in 5
Writes a new PHA file called "ABCD.PHA" with the current setting, the !
indicates that if ABCD.PHA already exists it is OVERWRITTEN.

.in -10
9) EXIT
.br
.in 5
Exits the task.

GRPPHA> EXIT 
.br
.in 5
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.

.in -5
GRPPHA> EXIT !ABCD.PHA
.br
.in 5
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.

.in -10
10) QUIT   
.br
.in 5
Quits from the task

GRPPHA> QUIT
.br 
.in 5
Exit the task without writing a new PHA file.

.in -10
11) HELP
.br
.in 5
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.

.in -10
.ih
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.

.ih
PARAMETERS
.ls infile [character]
 The input filename containing the PHA data in OGIP standard, as a BINARY
 table FITS extension
.le
.ls outfile [character]
 The name of the output file to be created (in OGIP standard format). The 
 default output file is GRPPHA.OUT
.le
.ls comm [character]
 The command string at the first prompt. 
.le
.ls tempc [character]
 The command string starting from the second prompt. 
.le
.ls 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.
.le
.ls (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.
.le
.ih
EXAMPLES

1) To manipulate the PHA file "my_file.pha" , and write to "my_file.grp"
with the changes if any, and default chattiness :
.br
.in 10
he> grppha my_file.pha myfile.grp
.br
.in -5
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 : 
.br 
.in 5
grppha> group 1 400 10
.br
.in -5
This command will group 1 to 400 with 10 bins in each group.
To show the current grouping :
.br 
.in 5
grppha> show grouping
.br 
.in -5
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 :
.br
.in 5
grppha> exit
.br
.in -10

.sp
2) To use "test.pha" as input PHA file, and use the default 
output file, with default chattiness (quiet) :
.br
.in 10 
he> grppha test.pha
.br
.in -5
To add a systematic error to channels 40 to 56 :
.br
.in 5
grppha> systematics 40-56 0.03
.br
.in -5
A 3% systematic error is added. Now to set bad 
channels, that is these channels will be ignored in XSPEC :
.br
.in 5
grppha> bad 11 20-40
.br
.in -5
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 :
.br
.in 5
grppha> show all
.br
.in -5
To exit the program without writing to a file :
.br
.in 5
grppha> quit
.br
.in -10

3) To use "bbxrt.pha" as input file, and "bbxrt.grp",as output
filename, with verbose chattiness :
.br
.in 10
he> grppha bbxrt.pha bbxrt.grp 20
.br
.in -5
To group the data with at least 30 raw counts in each
bin :
.br
.in 5
grppha> group min 30
.br
.in -5
The current changes can be written to a file, without
exiting grppha :
.br
.in 5
grppha> write bbxrt30.grp
.br
.in -5
The reset command can be used to set all the data as unbinned.
After this the data can be rebinned afresh. To reset :
.br
.in 5
grppha> reset grouping
.br
.in -5
To set bad channels by defining them in a file :
.br
.in 5
grppha> bad badfile.dat
.br
.in -5
To exit, and write a new PHA file :
.br
.in 5
grppha> exit 
.br
.in -10


4) To use "bbxrt.pha" as input file, and "bbxrt.grp",as output
filename, with entire command given on a single line :
.br
.in 10
he> grppha bbxrt.pha bbxrt.grp comm="group min 30 & exit"
.br
.in -10

.fi
.ih
BUGS
None known
.ih
SEE ALSO
.br
.nj
 Chanpha (xspec)  Legacy No.2  cal/sw/93-010
.br
.ju

.ih
LOG OF SIGNIFICANT CHANGES

.ls 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 
.le
.ls v1.0.0 (1993 March)
    Initial public release
.le

.ih
PRIMARY AUTHOR

.nj
Rehana Yusaf
.br
.nj
HEASARC
.br
.nj
NASA/GSFC
.br
.nj
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.br
.nj
(301) 286-6115
.ju
.endhelp

