NOTICE:
This Legacy journal article was published in Volume 4, February 1994, and has not been
updated since publication. Please use the search facility above to find regularly-updated information about
this topic elsewhere on the HEASARC site.
|
GRPPHA
Rehana Yusaf & Ian M. George
HEASARC
OGIP Calibration Memo CAL/SW/93-010 Version: 1994 Jan 10
Contents
- INTRODUCTION
- INPUT PARAMETERS FOR GRPPHA
- COMMAND SUMMARY
- 3.1 HELP
- 3.2 GROUP
- 3.2.1 grppha>GROUP MINCHAN MAXCHANNCHAN
- 3.2.2 grppha>GROUP GRP_FILE.DAT
- 3.2.3 grppha>GROUP MIN RCNTS
- 3.3 BAD
- 3.3.1 grppha>BADMINCHAN-MAXCHAN
- 3.3.2 grppha>BAD BADFILE.DAT
- 3.4 GOOD
- 3.4.1 grppha>GOOD MINCHAN-MAXCHAN
- 3.4.2 grppha>GOOD GOODFILE.DAT
- 3.5 SYSTEMATICS
- 3.5.1 grppha>SYSTEMATICS MINCHAN-MAXCHAN ERR
- 3.5.2 grppha>SYSTEMATICS SYSFILE.DAT
- 3.6 SHOW
- 3.6.1grppha>SHOW GROUPING
- 3.6.2 grppha>SHOW QUALITY
- 3.6.3 grppha>SHOW SYSTEMATICS
- 3.6.4 grppha>SHOW ALL
- 3.6.5 grppha>SHOW KEYWORDS
- 3.7 RESET
- 3.7.1 grppha>RESET GROUPING
- 3.7.2 grppha>RESET QUALITY
- 3.7.3 grppha>RESET SYSTEMATICS
- 3.7.4 grppha>RESET ALL
- 3.8 CHKEY
- 3.8.1 grppha>CHKEY KEYWORD NEWVALUE
- 3.9 WRITE.
- 3.9.1 grppha>WRITE ABCD.PHA
- 3.9.2 grppha>WRITE !ABCD.PHA
- 3.10 EXIT
- 3.10.1 grppha>EXIT
- 3.10.2 grppha>EXIT !ABCD.PHA
- 3.11 QUIT
- WARNINGS ON USAGE
- EXAMPLES
- FUTURE ENHANCEMENTS
Summary
GRPPHA is a task within the HEASARC sub-package of FTOOLS to define the channel
grouping card, quality flags and fractional systematic errors associated with a
FITS PHA file conforming to an OGIP standard format. Here we describe in
detail the required user inputs, currently available commands and limitations
of the task. A number of examples are also provided for illustration.
1 Introduction
GRPPHA is an interactive command driven task to define (or redefine) and/or
display the grouping (binning) and 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 setting 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.
On entry, the task displays the values of the keywords mandatory for FITS PHA
extension conforming to an OGIP standard format (see Arnaud, George &
Tennant 1992; George & Arnaud 1993). The user is then repeatedly prompted
for commands until they exit (or quit) the task.
The most recent version of this users guide is available via anonymous ftp on
heasarc.gsfc.nasa.gov as /caldb/docs/memos/cal_sw_93_10.ps.
It should be noted that unlike its predecessor CHANPHA, none of the commands
available within GRPPHA change the actual PHA dataset itself (i.e., the
observed counts vs. channel histogram) in any way. Instead, the necessary
grouping, quality and systematic error information for each channel is written
alongside the PHA dataset to be picked up by downstream software (e.g.
XSPEC).
2 Input Parameters for GRPPHA
The following parameters are currently used:
- infile [file name]
The input filename containing the PHA data in OGIP standard, as a BINTABLE
FITS extension
- outfile [output file]
The name of the output file to be created (in OGIP standard format).
- comm [command string]
The command string (see Section 3)
- chatter [integer] (hidden)
The value of the chatter flag, useful for reassurance and diagnostics
purposes. The default value is chatter=9, with chatter
<= 5 being very quiet and chatter >= 20 very verbose.
There are also a number of other hidden parameters which are used internally by
the task, and which should not be changed by users.
3 Command Summary
There are 7 "families" of command strings currently implemented:
1. group - to define the channel grouping
2. bad - to set channels to bad quality (can be 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
along with the following straightforward utilities:
- help - interactive help on the task, its commands and their syntax
- write - to write a new PKA file with the current settings
- exit - to exit the task (writing a new file)
- quit - to quit the task
Several commands can be specified on the command line by separating them with
an ampersand (&). See example 4 in section 5.
The various capabilities, limitations syntax of each of the above are listed in
the following subsections.
3.1 HELP
An interactive help which lists the available commands
Example: grppha> help
displays the top-level help. The commands
grppha> commands
grppha> ?
will give the same information.
Interactive help on a particular command (and the syntax), can be obtained
using
grppha> help COMMAND
where COMMAND is one the commands listed above.
Example: grppha> help group
gives help upon the commands available to set the grouping flags.
3.2 GROUP
Sets the grouping flags such that the PHA dataset can be rebinned by downstream
software. 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 group or 'bin' (value = + 1), and which are part of a continuing bin (-1).
Thus the number of channels (and the channel-numbering scheme itself) in any
PHA written by GRPPHA will be the same as that for the input file. (See also
Section 3.7.1.)
There are 3 methods by which the grouping can be set and they are listed in
sections 3.2.1, 3.2.2 and 3.2.3.
3.2.1 grppha>GROUP MINCHAN MAXCHAN NCHAN
The data is grouped from MINCHAN to MAXCHAN (inclusive) with NCHAN channels in
each group. Any 'spare' channels (at the high end of the specified channel
range when (MAXCHAN - MINCHAN + 1)/NCHAN is not an integer) will be left
ungrouped and the user informed. Any grouping requested which partially
overlaps a pre-existing grouping will be ignored and the user informed. A
maximum of 3 sets of groupings is allowed on the command line.
Example: grppha> 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.
3.2.2 grppha>GROUP GRPFILE.DAT
The grouping information is read (free-format) from the data file
GRPFILE.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.
3.2.3 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 high channel end of the dataset (which when added
together have less than RCNTS counts) are defined BAD by software
(Quality=2).
3.3 BAD
Sets the quality flags such that the specified channels can be ignored by
certain subsequent commands (such as GROUP MIN RCNTS described in Section
3.2.3) and downstream software (e.g. XSPEC). The quality flags of unspecified
channels are unchanged. All channels set bad within GRPPHA will have a quality
flag of either 2 or 5 (indicating a 'spare' and 'bad' channel respectively).
XSPEC can be told to ignore channels with Quality != 0 by issuing the
xspec>ignore bad command. (See also Section 3.7.2.)
There are 2 methods whereby channels can be set bad:
3.3.1 grppha>BAD MINCHAN-MAXCHAN
Channels between MINCHAN and MAXCHAN (inclusive) are set bad (Quality = 5). All
other channels will retain their previous quality flag. The hyphen in the above
command should be noted - 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 3 sets of channels are allowed on the command
line.
Example: grppha> bad 1 5-20 29 100
will set the quality flag such that channel 1, channels 5 through 20, channel
29 and channel 100 are defined to be bad.
3.3.2 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 that unlike when the command
is entered on the command line, dashes are illegal syntax in the file, and
single channels which are to be set bad must be specified by explicitly setting
MAXCHAN to be equal to MINCHAN.
3.4 GOOD
Sets the quality flags such that the specified channels are considered good
(Quality = 0) and hence will be used by certain subsequent commands (such as
GROUP MIN RCNTS described in Section 3.2.3) and downstream software (e.g.,
XSPEC). The quality flags of unspecified channels are unchanged. (See also
Section 3.7.2.)
There are 2 methods whereby channels can be set good:
3.4.1 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 flag. A
maximum of 3 sets of channels are allowed on the command line.
Example: grppha> good 2 6-18 99
will set the quality flag such that channel 2, channels 6 through 18 and
channel 99 are defined to be good.
3.4.2 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 that unlike when the
command is entered on the command line, dashes are illegal syntax in the file,
and single channels which are to be set good must be specified by explicitly
setting MAXCHAN to be equal to MINCHAN.
3.5 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 the SYS_ERR column is filled with the appropriate values, and the
command is therefore reversible. (See also Section 3.7.3.)
There are 2 methods whereby the systematic errors can be set:
3.5.1 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 counts or count rate for that channel). A maximum of
3 errors are permitted on the command line.
Example: grppha> systematics 20 0.02 30-40 0.01
will set channel 20 to have a systematic error of 2% and channels 30
through 40 to have an error of 1%.
3.5.2 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. Note that unlike when the command is entered on the command line, dashes
are illegal syntax in the file, and single channels which are to have an error
applied must be specified by explicitly setting MAXCHAN to be equal to
MINCHAN.
3.6 SHOW
Displays the current settings to the screen in a concise format.
3.6.1 grppha>SHOW GROUPING
Displays the current channel GROUPING cards to the screen.
Example: grppha> show group
will result is the display to the screen of the form:
--------
GROUPING
--------
Channel Grouping (Channel-Channel) :
-----------------------------------------------
4 - 5 of undefined grouping
6 - 84 are single channels
85 - 92 are grouped by a factor 2
93 - 128 of undefined grouping (Channel quality=bad)
-----------------------------------------------
where undefined indicates that the grouping flag is 0, for single channels the
grouping flag is 1, the start of a new bin has a grouping flag of 1, and
channels that are part of a continuing group have the grouping flag of -1.
3.6.2 grppha>SHOW QUALITY
Displays the QUALITY flags to the screen of all channels or ranges of channels
which are currently defined as bad.
Example: grppha> show quality
will result is the display to the screen of the form:
-------
QUALITY
-------
Bad Channels (Channel - Channel) :
--------------------------------------------
4 - 5 have quality 5
91 - 128 have quality 2
--------------------------------------------
where quality=5 indicates that the channel has been set bad by the
user, and quality=2 has been defined "dubious" by software. A full list of
possible quality flag values and their meaning is given in Arnaud et al.
(1992). As noted above, channels set bad within GRPPHA will have a quality flag
of either 2 or 5, and can be ignored within XSPEC by issuing the
xspec>ignore bad command.
3.6.3 grppha>SHOW SYSTEMATICS
Displays current fractional SYSTEMATIC errors to the screen for those channels
for which it is defined.
Example: grppha> show systematics
will result is the display to the screen of the form:
-----------------
SYSTEMATIC ERRORS
-----------------
Systematic Errors (Channel - Channel) :
---------------------------------------------
13 - 23 have systematic error 0.0300
24 - 20 have systematic error 0.0750
---------------------------------------------
indicating channels 13 to 23 (inclusive) have a systematic error of
3%, and channels 24 to 36 have a systematic error of 7.5%. All other channels
have no (i.e. a 0%) systematic error defined.
3.6.4 grppha>SHOW ALL
Displays the current channel GROUPING cards, QUALITY flags and fractional
SYSTEMATIC errors to the screen in the formats described above.
3.6.5 grppha>SHOW KEYWORDS
Displays all the mandatory PHA keywords, and their current values to the
screen.
3.7 RESET
Resets the current settings to 'null', NOT to those in the original input
file.
3.7.1 grppha>RESET GROUPING
Reset all the channel GROUPING flags to 1, that is to ungrouped (not to those
in the input file).
3.7.2 grppha>RESET QUALITY
Reset all the channel QUALITY flags to good (Quality = 0), regardless of the
original setting.
3.7.3 grppha>RESET SYSTEMATICS
Reset the fractional SYSTEMATIC errors to zero, (not to those in the input
file).
3.7.4 grppha>RESET ALL
Reset all the channel GROUPING card, QUALITY flags and fractional SYSTEMATIC
errors, as described above.
3.8 CHKEY
This command allows a keyword value to be changed. Currently users are
permitted to change the values only a subset of the mandatory keywords.
3.8.1 grppha>CHKEY KEYWORD NEWVALUE
The value of KEYWORD is changed to NEWVALUE. It should he noted that the
maximum allowed length for a number is 20 characters, and for a character
string (e.g. for filenames) is 60 characters.
Example: grppha> CHKEY AREASCAL 1.03
will change the value of AREASCAL keyword to 1.03.
3.9 WRITE
Writes an output PHA file with the current settings and including copies of any
other extensions present within the original input PHA file.
3.9.1 grppha>WRITE ABCD.PHA
Writes a new PHA file called ABCD.PHA. For the protection of users,
under Unix/Ultrix this command will produce an error message should a file of
this name already exist in the current directory. No new file will be written
and thus the pre-existing file will not be lost. Under VAX/VMS a new file will
be written (with a higher version number), and the user warned of the existing
file. An error message will also be returned if the requested filename is
illegal under that operating system. or (at the current time) if the requested
output filename is the same as the input PHA file[5].
This command does not stop the task, thus settings can be altered further and
subsequently written to another file if so desired.
3.9.2 grppha>WRITE !ABCD.PHA
Writes a new PHA file called "ABCD.PHA" irrespective whether a file of the same
name already exists in the current directory. Under Unix/Ultrix the
pre-existing file will thus be overwritten, under VAX/VMS the pre-existing file
will not be deleted but the user will not be warned of its existence.
3.10 EXIT
Exits the task, after writing an output file.
3.10.1 grppha>EXIT
Exit the task, first writing a new PHA file with the name as specified by the
input parameter outfile with the final settings, and including copies
of any other extensions present within the original input PHA file. The rules
regarding illegal filenames given in Section 3.8 apply.
3.10.2 grppha>EXIT !ABCD.PHA
Exit the task, first writing a new PHA file "ABCD.PHA" irrespective whether a
file of the same name already exists in the current directory. Under
Unix/Ultrix the pre-existing file will thus be overwritten; under VAX/VMS the
pre-existing file will not be deleted but the user will not be warned of its
existence. The specification of the output filename in this way overrides the
value given via the input parameter outfile.
3.11 QUIT
Quits the task.
Example: grppha> quit
Exits the task without writing the PHA file specified by the outfile
parameter.
4 Warnings on Usage
When the grouping command grppha> group MINCHAN MAXCHAN NCHAN is
used and an overlap occurs with channels for which the grouping has previously
been defined, the grouping of the channels in the region of overlap is left
unchanged and the user warned. The grouping is however set (if possible) for
all channels outside the region of overlap. Users wishing to overwrite a
pre-existing grouping should first use the grppha>reset group
command.
The grppha> group min command will overwrite any grouping flags
previously set.
When using input ASCII files with the grppha>bad,
grppha>systematics, and grppha>good commands, filenames
containing hyphens are not permitted.
5 Examples
- To manipulate the PHA file "myfile.pha' and write to "myfile.grp' with the
changes if any, anti default chattiness:
unix> 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 grppha>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 that in addition to the extension containing the PHA data, all other
extensions in the input file are copied:
grppha> exit
- To use "test.pha" as input PHA file, and use the default output
file, with default chattiness (quiet):
unix> grppha test.pha
To add a 3% systematic error to channels 40 to 56:
grppha> systematics 40 56 0.03
Now to set a number of channels 'bad' (such that they can 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
- To use "bbxrt.pha" as the input file, and "bbxrt.grp" as output
filename, with verbose chattiness:
unix> 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 reading a list of such channels from a file:
grppha> bad badfile.dat
To exit, and write a new PHA file (overwriting test.pha, should it
exist):
grppha> exit !test.pha
- To use GRPPHA in a non-interactive manner with no chatter:
unix> grppha infile='test.pha' outfile='new.pha' chatter=0 comm='group
1 2048 4&bad 1-10&exit'
6 Future Enhancements
The following enhancements are planned in the near future (mainly to reproduce
the functionality of the old XANADU task CHANPHA):
- Allow the use of "wild" cards in the specification of channel ranges for many
of the commands
- Add commands such as grppha> group SASS (which would only be
allowed in the case of PHA files from the ROSAT PSPC) to explicitly set the
grouping card to be equivalent to the 34 standard bins used by the SASS
processing.
- grppha>time to change the active integration time
- Allow the overwriting of the input file, should it be so desired.
The authors would appreciate any comments, suggestions for additional
enhancements etc. users may have.
References
Arnaud, K.A., George, I.M., Tennant, A.F., 1992. Legacy, 2, 65
(OGIP/92-007).
George, I.M. Arnaud, K.A., 1993, OGIP Memo OGIP/92-007a, available via
anonymous ftp on heasarc.gsfc.nasa.gov from the /caldb/docs/memos directory.
Proceed to the next article
Return to the previous article
Select another article
HEASARC Home |
Observatories |
Archive |
Calibration |
Software |
Tools |
Students/Teachers/Public
Last modified: Wednesday, 20-Oct-2021 10:49:23 EDT
| 
