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.
This task is primarily designed for input files that can fit within
memory. If memory=NO, performance will be significantly degraded.
Consider using ftmergesort for large files.
The task will function with tables that have variable-length columns,
but only if startrow and nrows are the default (full table 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.
- (startrow = 0) [integer]
- Starting row number to sort, or 0 to use first row. Rows before
startrow are not copied to the output.
- (nrows = 0) [integer]
- Number of rows to sort, or 0 to use all rows from startrow to the
end of the file. Rows after startrow+nrows are not copied to the output.
- (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,
ftmergesort
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
Apr 2019