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
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).
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 & 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 8 "families" of command strings currently implemented:
- group - to define the channel grouping
- bad - to set channels to bad quality
(can be ignored by XSPEC etc)
- good - to (re)set channels to good quality
- systematics - to set the fractional systematic error of the data
- show - to display the current settings to the terminal
- reset - to remove any current settings
- chkey - to change keyword value
- dump - to write an ASCII file of various current values
along with the following straightforward utilities:
- help - interactive help on the task, its commands and
their syntax
- write - to write a new PHA 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
as follows:
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.
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:
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).
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:
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.)
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:
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
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:
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.)
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 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).
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.
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.
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.
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.
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.
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:
3.9.1 grppha > DUMP GROUP GRP_FILE.DAT
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).
3.9.2 grppha > DUMP SYSTEMATICS SYSFILE.DAT
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).
3.9.3 grppha > DUMP QUALITY QUALFILE.DAT
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.
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.
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:
- setting the hidden boolean parameter clobber to yes
prior to entering the GRPPHA, or
- making use of the "!"-convention described in
Section 3.10.2.
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.
Exits the task, after writing an output file.
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.
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
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.
5 EXAMPLES
- To manipulate the PHA file "my_file.pha" , and write to
"my_file.grp" with the changes if any, and 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 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 have been suggested and/or
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
The authors would appreciate any comments, suggestions for additional
enhancements etc users may have.
ACKNOWLEDGEMENTS
We thank Nick White, Keith Arnaud, Tahir Yaqoob, Paul Nandra
and Jane Turner for useful suggestions and comments.
REFERENCES
Arnaud, K.A., George, I.M. & Tennant, A.F.,
OGIP/92-007
Versions available:
PDF,
HTML
Also see Arnaud et al 1992. Legacy, 2, 65.
George, I.M. & Arnaud, K.A.,
OGIP/92-007a
Versions available:
PDF,
HTML
USEFUL LINKS TO OTHER HTML PAGES
The following useful links are available: