dmsort

Synopsis

Sort a table.

dmsort infile outfile keys [copyall] [clobber] [verbose]

Description

Sort a table block on a given column or columns. Each sort key must be a column in the input block, optionally preceded by a "-" to indicate a descending order sort. If more than one key is given, the order of the keys indicates priority.

The result is that the rows of the block are sorted as specified. The data subspace and header are copied unchanged.

Example 1

dmsort "data1.fits[EVENTS]" data2.fits keys=-time clobber=yes

Sorts data in the EVENTS block by time column in descending order. Prints sorted block and copies all other blocks from data1.fits into data2.fits. Will overwrite data2.fits if it already exists.

Example 2

dmsort "data1.fits[EVENTS]" data2.fits keys=dety,-detx copyall=no

Sorts data in the EVENTS block first by dety column in ascending order and then by detx column in descending order. Prints sorted block from data1.fits into data2.fits, but does not copy any other blocks from data1.fits. Since the clobber keyword default is set to 'no', data2.fits will not be overwritten and sort results will not be saved if it already exists.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input file and block

The input file and the block which needs to be sorted.

Parameter=outfile (file required filetype=output)

The sorted output file

Where the sorted block is to be written.

Parameter=keys (string required)

Specify sort keys

Used to specify sort keys. Each sort key must be a column in the input block, optionally preceded by a "-" to indicate a descending order sort. If more than one key is given, the order of the keys indicates priority.

Parameter=copyall (boolean default=yes)

Specify whether remaining blocks in the input file is to be copied.

Used to specify whether remaining blocks in the input file will be copied into output file unchanged or not. If "copyall=yes", remaining blocks in the input file are copied into the output file unchanged; otherwise they are omitted.

Note that while the time subspace *might* be stored in separate extensions (GTI blocks), it is usually part of the file subspace and will be included in the output file automatically (e.g. even if "copyall=no"). Occasionally using "copyall=yes" will result in duplicate GTIs being written to the output file.

Parameter=clobber (boolean default=no)

Clobber exisiting files?

Used to specify whether or not to clobber existing file that has the same name as the specified output file (only DM dataset will be clobbered).

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

Specify verbose level

Verbose can be from 0 to 5, generating different amounts of debugging output.

Changes in CIAO 4.4

• Bug fix: using "copyall=no" with the "opt=text/simple" format.

  The text/simple ASCII format does not support IMAGE blocks. When sorting a table with the default value of the dmsort copyall parameter (yes), the tool attempted to copy the other blocks from the input file, including the NULL PRIMARY image.

  unix% dmsort simple.fits "simple.sort.dat[opt kernel=text/simple]" keys=y
  # DMSORT (CIAO): Error adding full header. 
  

Bugs

Sorting string values  (14 Sep 2012)

dmsort can crash if sorting on a string column with duplicate values if a secondary sort criteria is used. For example

% cat sort.dat
#type   count_rate
star    1.0
star    1.3
pulsar  1.5
agn     0.4
% dmsort sort.dat sort.fits "type,count_rate" clob+
*** glibc detected *** dmsort: double free or corruption (fasttop): 0x000000000d73dc40 ***
======= Backtrace: =========
/lib64/libc.so.6[0x35126711df]
/lib64/libc.so.6(cfree+0x4b)[0x351267163b]
...

The exact screen output will likely be different. The bug is triggered because the 'type' column has two "star" values which causes the secondary sort on "count_rate" to be triggered.

Sorting on just the string column works as expected.

See Also

dm

dmfiltering, dmopt

tools

dmappend, dmgroup, dmgti, dmjoin, dmmerge, dmpaste, dmtabfilt, dmtcalc, dmtype2split