NAME

fmemsort -- Sort the contents of a FITS table in memory

USAGE

        fmemsort infile[ext#] outfile columns method 

DESCRIPTION

This task sorts the rows in a FITS table based on the values in the specified columns of the table. The table is sorted in memory to maximize the sorting performance. The table may be sorted in ascending or descending order. Several sorting algorithms are available. This task produces a new FITS file containing the sorted table whose structure is determined by the parameters described below.

When sorting extremely large files it is recommended that the output FITS file be located on a different drive than the input FITS file. This is to minimize disk head seeks and hence improve I/O performance.

PARAMETERS

infile [file name]

The file name (and extension number in square brackets) of the FITS file. The extension number specifies the table to be sorted.

outfile [file name]

Name of the new FITS file to contain the sorted table extension. By default, the output file will consist of a copied primary array followed by the sorted ASCII or binary table extension, depending on the type of input file extension. If preceeded by !, an existing file of the same name will be overwritten.

columns [string list]

A list of column names appearing in the FITS table extension to be sorted in the order specified.

method = "heap" [string]

Sorting algorithm to be used. Currently supported algorithms are the "heap"(NlogN), "shell"(N**1.5) and "insert"(N**2) sort. The shell 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.

(ascend = yes) [boolean, yes=ascend, no=descend]

An optional boolean flag used to determine if sorting is to be done in ascending or descending order. This flag applies to all columns sorted.

(load2mem = yes) [boolean, yes=load, no=don't load]

An optional boolean flag used to determine if the whole FITS table containing the columns to be sorted should be loaded into system memory. This can speed up sorting times if the system resources are large enough.

(copyprime = yes) [boolean]

If true, the primary header and array of the input file will be copied to the output file.

(copyall = yes) [boolean]

Copy all other extensions (and the primary array) from input FITS file to the output FITS file? If true, the value of copyprime is ignored.

(unique = no) [boolean, yes=keep unique, no=keep all]

An optional boolean flag used to determine if rows with identical sort keys should be purged, keeping one unique row. Columns not included in the sort are not tested for uniqueness.

(history=yes) [boolean]

When this parameter is true, FMEMSORT will add a history record to indicate that it acted on the file.

(clobber = no) [boolean]

If true, an existing file with the same name as the requested output file will be overwritten.

EXAMPLES

1. Sort the time column found in the second table extension in ascending order in the FITS file test.fits

     
             ft> fmemsort test.fits[2] out.fits time

2. Sort using the X and Y columns found in the first extension in descending order with the insert method in the FITS file test.fits

     
             ft> fmemsort test.fits out.fits "X Y" method = "insert" ascend=no

BUGS

SEE ALSO

ftsort. fv, the interactive FITS file editor, can also be used to sort a FITS table.

CATEGORY