NAME

ftsort - Sort the rows in a FITS table.

USAGE

ftsort infile[ext][filters] outfile columns

DESCRIPTION

Create a sorted copy of the input table in which the rows are sorted in ascending or descending order based on the values in a specified column or set of columns in the table. If more than one column is specified then the rows that have the same value in the first column are sorted in order of the value in the second column, and so on for any further specified columns. Precede the column name with a minus sign to sort in descending order. Several different sorting algorithms are available: heap sort, shell sort, or insert sort.

PARAMETERS

infile [filename]
Input file name and optional extension name or number enclosed in square brackets of the table to be sorted (e.g., 'file.fits[events]'). If an explicit extension is not specified, then the first 'interesting' table in the input file will be sorted, i.e., the first table extension that is not a GTI (Good Time Interval) extension. Additional table filters may be appended to the file name, also enclosed in square brackets, as shown in the examples.

outfile [filename]
Output file name for the sorted file. Precede it with an exclamation point, !, (or \! on the Unix command line), to overwrite a preexisting file with the same name (or set the clobber parameter to YES).

columns [string list]
A comma separated list of the column names (or numbers) on which to sort the table. To sort in reverse order (from largest to smallest) put a minus sign in front of the column name. If more than one column is specified then the rows that have the same value in the first column are sorted in order of the value in the second column, and so on for any further specified columns.

(method = "heap") [string]
Sorting algorithm to be used. Supported algorithms are the "heap" (NlogN), "shell" (N**1.5) and "insert" (N**2) sort. The shell sort gives better performance with midsize data sets. The heap sort gives the best speed when dealing with large random datasets. The insertion sort works best when the dataset is very nearly sorted, i.e., one value out of place.

(memory = YES) [boolean]
Load the whole table into memory for sorting? This can speed up the sorting times if the system resources are large enough.

(unique = NO) [boolean]
Flag used to determine if rows with identical sort keys should be purged, keeping only one unique row. Columns not included in the sort are not tested for uniqueness.

(copyall = YES) [boolean]
If copyall = YES (the default) then all other HDUs in the input file will also be copied, without modification, to the output file. If copyall = NO, then only the single table HDU specified by infile will be copied to the output file along with the required null primary array.

(clobber = NO) [boolean]
If outfile already exists, then setting 'clobber = yes' will cause it to be overwritten.

(chatter = 1) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 5 will produce detailed diagnostic output, otherwise this task normally does not write any output.

(history = NO) [boolean]
If history = YES, then a set of HISTORY keywords will be written to the header of the sorted HDU to record the value of all the ftsort task parameters that were used to produce the output file.

EXAMPLES

Note that when commands are issued on the Unix command line, strings containing special characters such as '[' or ']' must be enclosed in single or double quotes.

1. Sort the input 'events' table on the time column values in ascending order. 

      ftsort 'in.fits[events]' out.fits time
2. Sort the input table using the X column as the primary sort key (in increasing order) and the Y column as the secondary sort key (in decreasing order since the column name is preceeded by a minus sign). 

      ftsort in.fits[events]' out.fits X,-Y
3. Sort a virtual EVENTS table. The output table will contain only those rows that have a PHA column value greater than 50, and will be sorted based on the 'time' column and using the 'shell' sort algorithm, 

      ftsort 'in.fits[events][pha > 50]' out.fits time method=shell
4. Sort a table of objects in order of increasing RA and DEC, and delete duplicate rows that have exactly the same RA and DEC values. 

      ftsort objects.fits out.fits ra,dec unique=yes

SEE ALSO

ftcopy, ftcalc, filenames, colfilter, rowfilter

fv, the interactive FITS file editor, can also be used to sort FITS tables.

The design of this task is based on the fsort and ftmemsort tasks in the ftools package.

LAST MODIFIED

July 2002