NAME
grppha2 -- Manipulates OGIP standard TYPEII PHA FITS file.
Both input and output files are of TYPEII PHA.
USAGE
grppha2 infile outfile
or
grppha2 infile outfile respfile=resp ancrfile=ancr
or
grppha2 infile.pha outfile.pha respfile=@resp ancrfile=@ancr
DESCRIPTION
GRPPHA2 is a tool to define or redefine the grouping (binning) &
quality flags, and the fractional systematic errors associated with
channels in a FITS PHA file. A new typeII FITS PHA file is written
which includes the latest settings. 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 (i.e., 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 GRPPHA2
commands and downstream software (eg XSPEC).
The commands are case insensitive and are provided either on the
command line, or in an ascii file. In the former case, the commands
need to be separated by a comma, while in the latter case, the file
name must be preceeded by "@" sign. See examples below.
A maximum of 50 commands can be given in a file.
NOTE: at the prompts for the spectra numbers and the command the user
can obtain help by typing "help" or "?".
Option provided for user to choose respfile and ancrfile column for
output file as hidden parameter. Otherwise specifically mentioned in
the command line, those columns will be used as in input file.
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) quit or q - to quit/exit the task
6) exit or x - to quit/exit the task
7) help or ? - interactive help
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:
- 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 pre-existing grouping
will also be ignored and the user informed.
e.g.: group 10 20 2
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.
- 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 the software
(QUALITY=2).
- 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 50 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
- 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:
- BAD MINCHAN MAXCHAN
-
Channels between MINCHAN and MAXCHAN (inclusive) are set
bad (Quality = 5).
e.g.: bad 5 20
will set the quality flag such that channels 5 through
20 are defined to be bad.
- 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 50 lines (sets of channel ranges,
one per line) with the syntax MINCHAN MAXCHAN where these
have the same meanings as above.
- 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:
- GOOD MINCHAN MAXCHAN
-
Channels between MINCHAN and MAXCHAN (inclusive) are set
good should they not be so already.
e.g.: good 6 18
will set the quality flag such that channels 6
through 18 are defined to be good.
- 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 50 lines (sets of channel ranges,
one per line) with the syntax MINCHAN MAXCHAN where these
have the same meanings as above.
- 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:
- 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).
- 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 50
lines (sets of channel ranges, one per line) with the
syntax MINCHAN MAXCHAN ERR where these have the same meanings
as above.
- 5) QUIT or Q
-
Quits from the task without performing any command..
Same as Exit
- 6) EXIT or X
-
Exits the task without performing any command
Same as Quit
- 7) HELP or ?
-
Interactive help, lists available commands.
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
and an overlap occurs with a previous setting, the data is rebinned
after the overlap if applicable. Note: The "group min" command does
not check for any overlaps.
PARAMETERS
- infile [character]
-
The input filename containing the TYPEII 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) containing TYPEII PHA data.
- spectra_num [character]
-
The range of spectra (rows) to be input. The default of "-" means
all rows. The first ten rows could be specified as "1-10" or just
"-10". To input the first ten rows and all rows from 100 through
the last (inclusive), use "1-10,100-". An input of "1,3,7,23" will
do only those four rows."
- command [character]
-
The command string at the prompt.
If string starts with "@" then it reads the ascii file following
the @ sign.
"help" displays help on available commands.
"help group" displays help on group command.
- respfile [character][hidden]
-
The root name of the response file column to be written.
This is a hidden parameter and need to be provided at the command
line. If this parameter is provided by the user as respfile=root,
then the respfile column of the output file contains filenames with
"root_rowid[i].rmf"
Another way to use response file is if user uses respfile=@resp.
In this case, the response file names for output file are read from
the ascii file "resp".
- ancrfile [character][hidden]
-
The root name of the ancr file column to be written.
This is a hidden parameter and need to be provided at the command
line. If this parameter is provided by the user as ancrfile=root,
then the ancrfile column of the output file contains filenames with
"root_rowid[i].arf"
Another way to use ancronse file is if user uses ancrfile=@ancr.
In this case, the ancr file names for output file are read from
the ascii file "ancr".
- (chatter = 5) [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
To manipulate the PHA file "infile.pha", and write to "outfile.pha"
with the grouping commands,:
grppha2 infile.pha outfile.pha
grppha2 infile.pha outfile.pha respfile=root1 ancrfile=root2
grppha2 infile.pha outfile.pha respfile=@resp ancrfile=@ancr
BUGS
None known
SEE ALSO
GRPPHA
LOG OF SIGNIFICANT CHANGES
v1.0.0 (1999 May)
Initial public release
v2.0.0 (1999 June)
Provided option to use respfile and ancrfile names in the
command line.
v3.0.0 (2002 Oct)
fixed bug
PRIMARY AUTHOR
Banashree M Seifert
MODIFIED BY
Chunhui Pan
CATEGORY
Oct2002 ftools.integral