dmtype2split

Synopsis

Create a type 1 PHA output file for specified rows of a type 2 PHA file.

dmtype2split  infile outfile [clobber] [verbose]

Description

CIAO extends the concept of type 1 and type 2 PHA files to general tables. A type 1 file of size N is a simple table consisting of scalar columns each with N rows. A type 2 file of size N x M is a table with M rows in which each column is either scalar or an array of size N. Each row of the type 2 file corresponds to a whole type 1 file, and `dmtype2split' performs this mapping.

The mapping consists of turning each array column entry from `sideways' to `vertical', so that an array of 4096 values becomes a column with 4096 rows. Scalar columns map to keywords in the output file.

Each of the specified rows in the type 2 file is copied to a type 1 file. Each output file has the basic header keywords and subspace copied from the input. If the input file is a pha file, keywords required by the OGIP format are also written; otherwise, generic keywords are written. For each scalar column in the input, the coordinate keyword information is written, and the datatype, value, and unit are written as a keyword. For each input column that is an array, a column is created from the datatype, value, and unit; the row of input data is read and written to the output column.

Specifying Rows

The rows can be specified in any order, but the Data Model sorts them numerically before processing. If supplying several input rows and a stack of output filenames, it is recommended that the rows be given in order so that the mapping to the filename is clear. The rows may be comma- or colon-delimited, e.g., "1:4,6,9:12". A colon-delimited interval is inclusive (e.g., "2:5" means rows 2, 3, 4, 5). If the number of rows specified does not equal the number of output files specified, the program exits with an error message. If no rows are specified, rows 1:n are processed, where n is the number of files in the outfile stack.

Example 1

dmtype2split in3.fits"[#row=1:3,6]" @outlist

From the type 2 input file, create 4 type 1 output files (1 each for rows 1, 2, 3, and 6 ). In this case the output file stack outlist must have 4 file names.

Example 2

dmtype2split in3.fits @outlist

From the type 2 input file, create type 1 output files (1 each for rows 1, 2, 3,..n where n is the number of output files in outlist).

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The type 2 PHA input file.

Parameter=outfile (file required filetype=output stacks=yes)

The output dataset or stack.

Parameter=clobber (boolean default=no)

Specifies if an existing output file should be overwritten.

Parameter=verbose (integer default=0 min=0 max=5)

Specifies the level of verbosity in displaying diagnostic messages (0-5).

Bugs

Caveats

The extension name for the output file must be included as part of the output file name(s).  (14 Sep 2012)

Since dmtype2split is used for many different types of files it does not set the extension name, rather leaving it up to the user to specify. If the block name is omitted, the basename (no path) of the file name is used.

unix% dmtype2split "pha2[#row=1]" pha1
unix% dmlist pha1 blocks
 
--------------------------------------------------------------------------------
Dataset: pha1
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: pha1                           Table         7 cols x 8192     rows

Workaround:

As some analysis systems require certain files to contain specific block names to comply with different standards, the block name may need to be set as shown below

unix% dmtype2split "pha2[#row=1]" "pha1[SPECTRUM]"
unix% dmlist pha1 blocks
 
--------------------------------------------------------------------------------
Dataset: pha1
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: SPECTRUM                       Table         7 cols x 8192     rows

See Also

chandra

eventdef

dm

dmfiltering, dmopt

tools

dmappend, dmgroup, dmgti, dmjoin, dmmerge, dmpaste, dmsort, dmtabfilt, dmtcalc, tg_bkg, tg_create_mask, tg_resolve_events, tgdetect, tgextract, tgextract2, tgidselectsrc, tgmatchsrc