HEASARC Staff Scientist Position - Applications are now being accepted for a Staff Scientist with significant experience and interest in the technical aspects of astrophysics research, to work in the High Energy Astrophysics Science Archive Research Center (HEASARC) at NASA Goddard Space Flight Center (GSFC) in Greenbelt, MD. Refer to the AAS Job register for full details.

Search:

[Advanced Search]



Active Guest Observer Facilities/Science Centers
AstroSat BurstCube
CALET Chandra
Fermi INTEGRAL
IXPE MAXI
NICER NuSTAR
SRG eROSITA
  /ART-XC		 Swift
TESS XL-Calibur
XMM-Newton XRISM
Historic Guest Observer Facilities/Science Centers
AGILE ASCA
BeppoSAX CGRO
COBE EUVE
GALEX HaloSat
Hitomi HETE-2
LPF DRS ROSAT
RXTE Suzaku
WMAP  
Virtual Observatory/
Cloud Computing
HEASARC in the VO IVOA
NAVO HEASARC in the Cloud
NASA Archives
ADS EOSDIS
ExoArchive HORIZONS
IRSA KOA
LAMBDA MAST
NED NSSDCA
PDS SDAC
SPDF SSC

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

  1. INTRODUCTION
  2. INPUT PARAMETERS FOR GRPPHA
  3. 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
  4. WARNINGS ON USAGE
  5. EXAMPLES
  6. 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

  1. 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
  2. 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
  3. 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
  4. 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.

    Next Proceed to the next article Previous Return to the previous article

    Contents Select another article

    HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public
    Last modified: Wednesday, 20-Oct-2021 10:49:23 EDT

    HEASARC Staff Scientist Position - Applications are now being accepted for a Staff Scientist with significant experience and interest in the technical aspects of astrophysics research, to work in the High Energy Astrophysics Science Archive Research Center (HEASARC) at NASA Goddard Space Flight Center (GSFC) in Greenbelt, MD. Refer to the AAS Job register for full details.