NAME

ftgrouppha -- modifies the GROUPING column in a pha file using a number of possible criteria

USAGE

ftgrouppha [infile=]filename1 (backfile=backfilename) [outfile=]filename2 [grouptype=]bmin/constant/min/snmin/opt [groupscale=]# (minchannel=-1) (maxchannel=-1) (respfile=respfilename) (templatefile=templatefilename) (rows="-") (clobber=yes/no)

DESCRIPTION

The GROUPING column in a pha file is used by xspec and other programs to determine how to bin up spectra on read in. This task provides several ways to set the GROUPING column.

grouptype=bmin sets up a binning with a minimum number of counts in each bin in the background file with the minimum set using groupscale.

grouptype=constant sets up uniform binning by the factor given by groupscale. For instance, if groupscale=2 then GROUPING is set to bin by a factor of two in xspec.

grouptype=min sets up a binning with a minimum number of counts in each bin with the minimum set using groupscale.

grouptype=snmin sets up a binning with a minimum signal-to-noise ratio in each bin with the minimum set using groupscale. If a background file has been specified then the signal-to-noise will be for background-subtracted spectra.

grouptype=opt sets up a binning using the Kaastra & Bleeker (2016; A&A 587, A151) optimal binning scheme. Note that this option ignores any minchannel and maxchannel set.

grouptype=optmin sets up a binning using the Kaastra & Bleeker as for grouptype=opt, but with the additional requirement of a minimum number of counts set using groupscale. (i.e. optmin is the joint requirement of both "min" and "opt" grouptypes, whichever would group more).

grouptype=optsnmin sets up a binning using the Kaastra & Bleeker as for grouptype=opt, but with the additional requirement of a minimum signal/noise set using groupscale. (i.e. optsnmin is the joint requirement of both "snmin" and "opt" grouptypes, whichever would group more).

grouptype=file uses the GROUPING read in from the spectrum file specified by the templatefile parameter.

If minchannel and/or maxchannel are set to non-negative values then any grouping is restricted to the channel range they specify.

PARAMETERS

infile [filename]
The name of the pha file whose GROUPING column is to be set.

(backfile=none) [filename]
The name of a background pha file which will be used if grouptype=snmin. If this is given as % then the background file from the BACKFILE in the input file is used. If this is not NONE then it will be written to the BACKFILE keyword in the ouput file.

outfile [filename] The name of the output pha file with the modified GROUPING column. This should not be the same as infile.

grouptype [character string]
The grouping mode to be used. Can be bmin, constant, min, snmin, opt, optmin, optsnmin, of file.

groupscale [real]
The scale for the grouping. If grouptype=constant this is the binning factor, if grouptype=min, bmin, or optmin it is the minimum number of counts per bin, and if grouptype=snmin or optsnmin it is the minimum signal-to-noise ratio per bin.

(minchannel="-1") [integer]
The start channel for any grouping. If set to a negative number then the first channel in the spectrum is used.

(maxchannel="-1") [integer]
The end channel for any grouping. If set to a negative number then the last channel in the spectrum is used.

(respfile=none) [filename]
The name of a response file which will be used if grouptype=opt. If this is given as % then the response file from the RESPFILE in the input file is used. If this is not NONE then it will be written to the RESPFILE keyword in the ouput file.

(templatefile=none) [filename]
The name of a spectrum file whose GROUPING column will be used if grouptype=filet.

(rows="-") [character string]
The range of rows to group. The default value of "-" means operate on all rows. The first ten rows could be specified as rows="1-10". To operate on the first three rows and all rows from 11, use rows="1-3,11-". rows="3,5,7" will select only these three rows.

(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

1. Grouping by a constant factor 

ftgrouppha infile=file1.pha outfile=fileout.pha grouptype=const groupscale=4
2. Grouping to a minimum number of counts per bin 

ftgrouppha infile=file1.pha outfile=fileout.pha grouptype=snmin groupscale=3.0
3. Grouping to a minimum S/N ration including background 

ftgrouppha infile=file1.pha backfile=back1.pha outfile=fileout.pha grouptype=snmin groupscale=3.0
4. Grouping using the Kaastra & Bleeker optimal binning algorithm 

ftgrouppha infile=file1.pha respfile=resp1.rmf outfile=fileout.pha grouptype=opt
5. Grouping to a minimum number of counts per bin in the background file 

ftgrouppha infile=file1.pha backfile=back1.pha outfile=fileout.pha grouptype=bmin groupscale=1
6. Grouping using the Kaastra & Bleeker optimal binning algorithm over a subset of channels 

ftgrouppha infile=file1.pha respfile=resp1.rmf outfile=fileout.pha grouptype=opt minchannel=100 maxchannel=8000
7. Grouping using a template spectrum file 

ftgrouppha infile=file1.pha templatefile=file2.pha outfile=fileout.pha grouptype=file
8. Grouping using the Kaastra & Bleeker optimal binning algorithm plus minimum of 100 counts per grouped bin 

ftgrouppha infile=file1.pha respfile=resp1.rmf outfile=fileout.pha grouptype=optmin groupscale=100 minchannel=100 maxchannel=8000
9. Grouping using the Kaastra & Bleeker optimal binning algorithm plus a minimum signal/noise of 3 per grouped bin 

ftgrouppha infile=file1.pha respfile=resp1.rmf outfile=fileout.pha grouptype=optsnmin groupscale=3.0 minchannel=100 maxchannel=8000
10. Grouping all rows by a constant factor in a type II file 

ftgrouppha infile=fileII.pha outfile=fileoutII.pha grouptype=const groupscale=4
11. Grouping by a constant factor in a type II file for even numbered rows 

ftgrouppha infile=fileII.pha outfile=fileoutII.pha grouptype=const groupscale=4 rows="2,4,6,8"

LAST MODIFIED

September 2022