Last modified: December 2013

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/dmsort.html
AHELP for CIAO 4.13

dmsort

Context: tools

Synopsis

Sort a table.

Syntax

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.


Examples

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

name type ftype def min max reqd
infile file input       yes
outfile file output       yes
keys string         yes
copyall boolean   yes      
clobber boolean   no      
verbose integer   0 0 5  

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.


Bugs

Sorting on multiple columns stops after first string column.

When sorting on string columns, any remaining sort columns (keys) may not sorted correctly. For example:

% dmlist data.dat cols,data
 
--------------------------------------------------------------------------------
Columns for Table Block blek2.dat
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   critter                           String[3]                           
   2   size                              String[5]                           
   3   age                               Real8          -Inf:+Inf            
   4   name                              String[7]                           
 
--------------------------------------------------------------------------------
Data for Table Block data.dat
--------------------------------------------------------------------------------
 
ROW    critter size    age                  name
 
     1 cat   small                    1.0 eyelid   
     2 cat   small                    2.0 eyelash  
     3 cat   big                      3.0 eyebrow  

% dmsort data.dat out.dat key=critter,-age clob+
% dmlist out.dat data,clean
#  critter size    age                  name
 cat   small                    2.0 eyelash  
 cat   small                    1.0 eyelid   
 cat   big                      3.0 eyebrow  

We can see in this example that the secondary sort on age is incorrect; the first row should be with age=3.0.

See Also

dm
dmfiltering, dmopt
tools
dmappend, dmgroup, dmgti, dmjoin, dmmerge, dmpaste, dmtabfilt, dmtcalc, dmtype2split