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.
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. For example:
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. For example:
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. For example:
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 256. 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 256. 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 to be
executed. Multiple commands can be entered by separating
them with an ampersand ("&")
- 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 :
prompt% 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) :
prompt% 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 :
prompt> 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
4) To use "bbxrt.pha" as input file, and "bbxrt.grp",as output
filename, with entire command given on a single line :
prompt> grppha bbxrt.pha bbxrt.grp comm="group min 30 & 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
CATEGORY
July94 ftools.heasarc