.help fsort Sept92 ftools.futils
.ih
NAME
fsort -- Sort the contents of a FITS table
.ih
USAGE
fsort filename[ext#] column 
.ih
DESCRIPTION
This task sorts the rows in a FITS table based on the values in a
specified column of the table.  The table is sorted in place, so as a
precaution one should always save a copy of the table before running
this task.  Aborting this task once it has started can leave the FITS table
in a corrupted state.  The table may be sorted in ascending or
descending order, and multi-column sorting may also be performed.  The
later means that once the rows have been sorted on the value of the
first column, then all identical values in the first column will be
sorted in order of the second specified column, and so on.
.ih
PARAMETERS
.ls infile [file name]
The file name (and extension number in square brackets) of the FITS file
to be sorted.
.le
.ls columns [string list]
A list of column names appearing in the FITS table extension to be
sorted in the order specified.
.le
.ls method = "heap" [string]
Sorting algorithm to be used. Currently supported algorithms are the
"heap"(NlogN) and "insert"(N**2) sort.   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.
.le
.ls (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.
.le
.ls (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.
.le
.ih
EXAMPLES
1.  Sort the time column found in the second table extension in
ascending order in the FITS file test.fits
.nf

        ft> fsort test.fits[2] time
.fi

2.  Sort using the X and then the Y columns found in the first extension in
descending order in the FITS file test.fits, deleting duplicate rows
containing the same values of X and Y.
.nf

        ft> fsort test.fits  "X Y" ascend=no unique=yes
.fi
.ih
BUGS
.ih
SEE ALSO
ftsort, fv, the interactive FITS file editor, can also be used to sort a FITS table.
.endhelp
