.TH STILTS 1 "Mar 2017" "" "Stilts commands" .SH NAME stilts \- Starlink Tables Infrastructure Library Tool Set .SH SYNOPSIS .ad l .HP 7 .hy 0 \fBstilts\fR [-help] [-version] [-verbose] [-allowunused] [-prompt] [-bench] [-debug] [-batch] [-memory] [-disk] [-memgui] [-checkversion ] [-stdout ] [-stderr ] .br .PP \fBstilts\fR \fBhelp\fR[=\fI|*\fR] .hy .ad .SH DESCRIPTION STILTS provides a number of command-line applications which can be used for manipulating tabular data. Conceptually it sits between, and uses many of the same classes as, the packages STIL, which is a set of Java APIs providing table-related functionality, and TOPCAT, which is a graphical application providing the user with an interactive platform for exploring one or more tables. .PP Detailed help for each task is available with the \fBhelp\fR option of the task. .SH OPTIONS Some flags are common to all the tasks in the STILTS package, and these are specified after the stilts invocation itself and before the task name. They generally have the same effect regardless of which task is running. .TP \fB\-help\fR Prints a usage message for the \fIstilts\fR command itself and exits. The message contains a listing of all the known tasks. .TP \fB\-version\fR Prints the STILTS version number and exits. .TP \fB\-verbose\fR Causes more verbose information to be written during operation. Specifically, what this does is to boost the logging level by one notch. It may be specified multiple times to increase verbosity further. The flag \fI+verbose\fR can be used to do the opposite (reduce the logging level by one notch). .TP \fB\-allowunused\fR Causes unused parameter settings on the command line to be tolerated. Normally, any unused parameters on the command line cause a usage message to be output and the command to fail, on the assumption that if you've supplied a parameter setting that's not doing anything it is probably a mistake and you should be given a chance to correct it. But if this flag is set, you just get a warning through the logging system about any unused parameters, and the command is executed as if they weren't there. .TP \fB\-prompt\fR Most of the STILTS commands have a number of parameters which will assume sensible defaults if you do not give them explicit values on the command line. If you use the \fI-prompt\fR flag, then you will be prompted for every parameter you have not explicitly specified to give you an opportunity to enter a value other than the default. .TP \fB\-bench\fR Outputs the elapsed time taken by the task to standard error on successful completion. .TP \fB\-debug\fR Sets up output suitable for debugging. The most visible consequence of this is that if an error occurs then a full stacktrace is output, rather than just a user-friendly report. .TP \fB\-batch\fR Some parameters will prompt you for their values, even if they offer legal defaults. If you use the \fI-batch\fR flag, then you won't be prompted at all. .TP \fB\-memory\fR Encourages the command to use java heap memory for caching large amounts of data rather than using temporary disk files. The default is to use memory for small tables, and disk for large ones. This flag is in most cases equivalent to specifying the system property \fI-Dstartable.storage=memory\fR. .TP \fB\-disk\fR Encourages the command to use temporary files on disk for caching table data. The default is to use memory for small tables, and disk for large ones. Using this flag may help if you are running out of memory. This flag is in most cases equivalent to specifying the system property \fI-Dstartable.storage=disk\fR. .TP \fB\-memgui\fR Displays a graphical window while the command is running which summarises used and available heap memory. May be useful for profiling or understanding resource constraints. .TP \fB\-checkversion \fR Requires that the version is exactly as given by the string \fI\fR. If it is not, STILTS will exit with an error. This can be useful when executing in certain controlled environments to ensure that the correct version of the application is being picked up. .TP \fB\-stdout \fR Sends all normal output from the run to the given file. By default this goes to the standard output stream. Supplying an empty string or "\fI-\fR" for \fI\fR will restore this default behaviour. .TP \fB\-stderr \fR Sends all error output from the run to the given file. By default this goes to the standard error stream. Supplying an empty string or "\fI-\fR" for \fI\fR will restore this default behaviour. .SH STILT TASKS The following tasks are currently available: .TP \fBstilts-arrayjoin\fR(1) Adds table-per-row data as array-valued columns .TP \fBstilts-calc\fR(1) Evaluates expressions .TP \fBstilts-cdsskymatch\fR(1) Crossmatches table on sky position against VizieR/SIMBAD table .TP \fBstilts-cone\fR(1) Executes a Cone Search-like query .TP \fBstilts-coneskymatch\fR(1) Crossmatches table on sky position against remote cone service .TP \fBstilts-datalinklint\fR(1) Validates DataLink documents .TP \fBstilts-funcs\fR(1) Browses functions used by algebraic expression language .TP \fBstilts-pixfoot\fR(1) Generates Multi-Order Coverage maps .TP \fBstilts-pixsample\fR(1) Samples from a HEALPix pixel data file .TP \fBstilts-plot2d\fR(1) Old-style 2D Scatter Plot .TP \fBstilts-plot3d\fR(1) Old-style 3D Scatter Plot .TP \fBstilts-plothist\fR(1) Old-style Histogram .TP \fBstilts-regquery\fR(1) Queries the VO registry .TP \fBstilts-sqlclient\fR(1) Executes SQL statements .TP \fBstilts-sqlskymatch\fR(1) Crossmatches table on sky position against SQL table .TP \fBstilts-sqlupdate\fR(1) Updates values in an SQL table .TP \fBstilts-taplint\fR(1) Tests TAP services .TP \fBstilts-tapquery\fR(1) Queries a Table Access Protocol server .TP \fBstilts-tapresume\fR(1) Resumes a previous query to a Table Access Protocol server .TP \fBstilts-tapskymatch\fR(1) Crossmatches table on sky position against TAP table .TP \fBstilts-tcat\fR(1) Concatenates multiple similar tables .TP \fBstilts-tcatn\fR(1) Concatenates multiple tables .TP \fBstilts-tcopy\fR(1) Converts between table formats .TP \fBstilts-tcube\fR(1) Calculates N-dimensional histograms .TP \fBstilts-tgridmap\fR(1) Calculates N-dimensional density maps .TP \fBstilts-tjoin\fR(1) Joins multiple tables side-to-side .TP \fBstilts-tloop\fR(1) Generates a single-column table from a loop variable .TP \fBstilts-tmatch1\fR(1) Performs a crossmatch internal to a single table .TP \fBstilts-tmatch2\fR(1) Crossmatches 2 tables using flexible criteria .TP \fBstilts-tmatchn\fR(1) Crossmatches multiple tables using flexible criteria .TP \fBstilts-tmulti\fR(1) Writes multiple tables to a single container file .TP \fBstilts-tmultin\fR(1) Writes multiple processed tables to single container file .TP \fBstilts-tpipe\fR(1) Performs pipeline processing on a table .TP \fBstilts-tskymap\fR(1) Calculates sky density maps .TP \fBstilts-tskymatch2\fR(1) Crossmatches 2 tables on sky position .TP \fBstilts-votcopy\fR(1) Transforms between VOTable encodings .TP \fBstilts-votlint\fR(1) Validates VOTable documents .TP \fBstilts-xsdvalidate\fR(1) Validates against XML Schema .TP \fBstilts-plot2plane\fR(1) Draws a plane plot .TP \fBstilts-plot2sky\fR(1) Draws a sky plot .TP \fBstilts-plot2cube\fR(1) Draws a cube plot .TP \fBstilts-plot2sphere\fR(1) Draws a sphere plot .TP \fBstilts-plot2time\fR(1) Draws a time plot .SH SEE ALSO \fBstilts-\fI\fR(1) for all tasks, \fBtopcat\fR(1) .PP If the package stilts-doc is installed, the full documentation \fBSUN/256\fR is available in HTML format: .br \%file:///usr/share/doc/stilts/sun256/index.html .SH VERSION STILTS version 3.4.7-debian .PP This is the Debian version of Stilts, which lack the support of some file formats and network protocols. For differences see .br \%file:///usr/share/doc/stilts/README.Debian .SH AUTHOR Mark Taylor (Bristol University)