OGIP Calibration Memo CAL/SW/93-010
GRPPHA
Rehana Yusaf
&
Ian M George
Code 668,
Version: 1995 Feb 23
NASA/GSFC,
Greenbelt,
MD 20771
FTOOLS Version 3.3
|
Release | Sections Changed | Brief Notes |
Date | ||
1994 Jan 10 | Version published in Legacy, 4, 64 | |
1994 Jul 20 | All | Updated for FTOOLS v.3.0 |
1995 Jan 11 | All | Made compatible with LaTeX2HTML s/w |
1995 Jan 30 | Sections 3.10.1 & 3.9 | Updated for FTOOLS v.3.3 |
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 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.
It should be noted that unlike its predecessor CHANPHA,
none of the commands available within GRPPHA
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 downstream software (eg. XSPEC).
The following parameters are currently used:
There are 8 "families" of command strings currently implemented:
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
as follows:
An interactive help which lists the available commands
Interactive help on a particular command (and the syntax),
can be obtained using
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:
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 (eg
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:
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 (eg 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:
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.
(See also Section 3.7.3.)
There are 2 methods whereby the systematic errors can be set:
Displays the current settings to the screen in a concise format.
In addition any of the CHKEY keywords can be displayed in full
(even if it exceeds 80 characters). This is useful for character string
keywords such as the path and name of response matrices etc, which can
often get truncated in other standard displays available within GRPPHA.
Resets the current settings to 'null', NOT to those in the original input
file.
This command allows a keyword value to be changed. Currently
users are permitted
to change the values of only a subset of the mandatory keywords.
This command allows the current values of a number of quantities/settings
to be written to ASCII file. These ASCII files can be read back into
GRPPHA and hence the DUMP
facility is useful if the user wishes to apply the same settings
in future GRPPHA runs.
Currently there 3 quantities able to be DUMPed:
The current grouping information is written to an ASCII data file
"GRP_FILE.DAT",
each row of which lists the values of the MINCHAN MAXCHAN NCHAN for a
given group. This grouping information can then be read into
GRPPHA via the command grppha$>$GROUP GRP_FILE.DAT
(see Section 3.2.2).
The current fractional systematic errors are written to an ASCII data file
"SYSFILE.DAT",
each row of which lists the values of the MINCHAN MAXCHAN ERR.
These systematics can then be read into
GRPPHA via the command grppha$>$SYSTEMATICS SYSFILE.DAT
(see Section 3.5.2).
The channels which are currently flagged as BAD (only)
are written to an ASCII data file
"QUALFILE.DAT",
each row of which has the format MINCHAN MAXCHAN.
This quality flag information can then be read into
GRPPHA via the command
grppha$>$BAD QUALFILE.DAT
(see Section 3.3.2).
It should be noted that if the command
grppha$>$GROUP MIN
(see Section 3.2.3)
was used to define which channels are
currently flagged as bad, then the
grppha$>$DUMP QUALITY QUALFILE.DAT does not
differential between bad channels interactively defined by
the user (which have a Quality flag of 5) and those set
bad by the grppha$>$GROUP MIN command
(which have a Quality flag of 2) - all channels with a
non-zero quality flag are written to the output ASCII
file.
Writes an output PHA file with the current settings,
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 if desired.
GRPPHA v.2.0.0 (and higher) allows the new PHA file to have
the same name as the input PHA file (and hence allows the input file
to be overwritten). This can be achieved either by:
Exits the task, after writing an output file.
Quits the task.
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
the grppha>reset group command.
The grppha> group min
command will overwrite any grouping flags previously set.
When using input ASCII files with the
commands, filenames containing 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.
The following enhancements have been suggested and/or
are planned in the near future
(mainly to reproduce the functionality of the old XANADU task
CHANPHA):
The authors would appreciate any comments, suggestions for additional
enhancements etc users may have.
We thank Nick White, Keith Arnaud, Tahir Yaqoob, Paul Nandra
and Jane Turner for useful suggestions and comments.
Arnaud, K.A., George, I.M. & Tennant, A.F.,
George, I.M. & Arnaud, K.A.,
The following useful links are available (in the HTML version of this
document only):
Contents
1 INTRODUCTION
2 INPUT PARAMETERS FOR GRPPHA
3 COMMAND SUMMARY
3.1 HELP
3.2 GROUP
3.2.1 grppha > GROUP MINCHAN MAXCHAN NCHAN
3.2.2 grppha > GROUP GRP_FILE.DAT
3.2.3 grppha > GROUP MIN RCNTS
3.3 BAD
3.3.1 grppha > BAD MINCHAN-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.1 grppha > 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.6.6 grppha > SHOW INFILE
3.6.7 grppha > SHOW CHKEYS
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 DUMP
3.9.1 grppha > DUMP GROUP GRP_FILE.DAT
3.9.2 grppha > DUMP SYSTEMATICS SYSFILE.DAT
3.9.3 grppha > DUMP QUALITY QUALFILE.DAT
3.10 WRITE
3.10.1 grppha > WRITE ABCD.PHA
3.10.2 grppha > WRITE !ABCD.PHA
3.11 EXIT
3.11.1 grppha > EXIT
3.11.2 grppha > EXIT !ABCD.PHA
3.12 QUIT
4 WARNINGS ON USAGE
5 EXAMPLES
6 FUTURE ENHANCEMENTS
1 INTRODUCTION
2 INPUT PARAMETERS FOR GRPPHA
There are also a number of other hidden parameters which are used
internally by the task, and which should not be changed by users.
The input filename containing the PHA data in OGIP standard, as a
BINTABLE FITS extension
The name of the output file to be created (in OGIP standard format).
The command string (see Section 3)
The value of the chatter flag, useful for reassurance & diagnostics
purposes. The default value is chatter=9, with chatter ≤ 5 being very
quiet and chatter ≥ 20 very verbose.
3 COMMAND SUMMARY
along with the following straightforward utilities:
3.1 HELP
Example: grppha> help
displays the top-level help. The commands
grppha> commands
grppha> ?
will give the same information.
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
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 6 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 ßpare" and left unbinned, and channels
21 to 30 can form a single bin.
3.2.2 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.
(See also the grppha> dump group command described in
Section 3.9.1.)
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
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 6 sets of channels are allowed on the command line.
Example: grppha> bad 1 5-20 29
will set the quality flag such that
channel 1, channels 5 through 20, and channel 29 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.
(See also the grppha> dump quality command described in
Section 3.9.3.)
3.4 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 6 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 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.
(See also the grppha> dump quality command described in
Section 3.9.3.)
3.5 SYSTEMATICS
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 6 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
have a systematic 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.
(See also the grppha> dump systematics command described in
Section 3.9.2.)
3.6 SHOW
3.6.1 grppha > SHOW GROUPING
Displays the current channel GROUPING cards to the screen.
Example: grppha> show group
will result in the following screen display:
--------
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 in the following screen display:
-------
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 in the following screen display:
-----------------
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 (ie 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.6.6 grppha > SHOW INFILE
Displays input filename.
3.6.7 grppha > SHOW CHKEYS
Displays names of keywords within the PHA file
that can have their values changed within GRPPHA
(via the command grppha> chkey, see Section 3.8).
Example: grppha> show respfile
will result in a screen display with the following format:
RESPFILE= /home/local/users/username/asca/gis/matrices/special/g2v3_1_1a.rmf
showing the current response file name.
3.7 RESET
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
3.8.1 grppha > CHKEY KEYWORD NEWVALUE
The value of KEYWORD is changed to NEWVALUE.
It should be noted that the maximum allowed
length for a number is 20 characters,
and for a character string (eg for filenames)
is 120 characters.
Example: grppha> CHKEY AREASCAL 1.03
will change the value of AREASCAL keyword to 1.03.
3.9 DUMP
3.9.1 grppha > DUMP GROUP GRP_FILE.DAT
3.9.2 grppha > DUMP SYSTEMATICS SYSFILE.DAT
3.9.3 grppha > DUMP QUALITY QUALFILE.DAT
3.10 WRITE
3.10.1 grppha > WRITE ABCD.PHA
Writes a new PHA file called ÄBCD.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 the operating system in use.
3.10.2 grppha > WRITE !ABCD.PHA
Writes a new PHA file called ÄBCD.PHA" irrespective of 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 latest (most current) version of the pre-existing file will
be overwritten.
3.11 EXIT
3.11.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, including copies of any other extensions present within
the original input PHA file.
The rules regarding illegal filenames given in Section 4
apply.
3.11.2 grppha > EXIT !ABCD.PHA
Exit the task, first writing a new PHA file
ÄBCD.PHA" irrespective of 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 latest (most current) version of the pre-existing file will
be overwritten.
The specification of the output filename in this way overrides the value
given via the input parameter outfile.
3.12 QUIT
Example: grppha> quit
Exits the task without writing the PHA file specified by the
outfile parameter.
4 WARNINGS ON USAGE
5 EXAMPLES
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
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
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
unix> grppha infile="test.pha" outfile="new.pha"
chatter=0 comm="group 1 2048 4 & bad 1-10 & exit "
6 FUTURE ENHANCEMENTS
ACKNOWLEDGEMENTS
REFERENCES
OGIP/92-007
(on-line versions available:
postscript,
HTML)
Also see Arnaud et al 1992. Legacy, 2, 65.
OGIP/92-007a
(on-line versions available:
postscript,
HTML)
USEFUL LINKS TO OTHER HTML PAGES