# STILTS - Starlink Tables Infrastructure Library Tool SetVersion 3.4-7

Mark Taylor
5 October 2022

## Abstract

STILTS is a set of command-line tools for processing tabular data. It has been designed for, but is not restricted to, use on astronomical data such as source catalogues. It contains both generic (format-independent) table processing tools and tools for processing VOTable documents. Facilities offered include crossmatching, format conversion, format validation, column calculation and rearrangement, row selection, sorting, plotting, statistical calculations and metadata display. Calculations on cell data can be performed using a powerful and extensible expression language.

The package is written in pure Java and based on STIL, the Starlink Tables Infrastructure Library. This gives it high portability, support for many data formats (including FITS, VOTable, text-based formats and SQL databases), extensibility and scalability. Where possible the tools are written to accept streamed data so the size of tables which can be processed is not limited by available memory. As well as the tutorial and reference information in this document, detailed on-line help is available from the tools themselves.

The STILTS application is available under the GNU General Public License (GPL) though most parts of the library code may alternatively be used under the GNU Lesser General Public License (LGPL).

## 1 Introduction

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. This document is mostly self-contained - it covers some of the same ground as the STIL and TOPCAT user documents (SUN/252 and SUN/253 respectively).

Currently, this package consists of commands in the following categories:

Generic table manipulation
tcopy, tpipe, tmulti, tmultin, tcat, tcatn, tloop, tjoin, arrayjoin, tgridmap, and tcube (see Section 6).
Crossmatching
tmatch1, tmatch2, tmatchn and tskymatch2 (see Section 7).
Plotting
plot2plane, plot2sky, plot2cube, plot2sphere and plot2time (also deprecated old-style plot commands plot2d, plot3d and plothist) (see Section 8).
Sky Pixel Operations
tskymap, pixfoot and pixsample.
VOTable
votcopy and votlint.
Virtual Observatory access
cdsskymatch, cone, coneskymatch, tapquery, tapresume, tapskymatch, taplint, datalinklint and regquery.
SQL databases
sqlclient, sqlupdate and sqlskymatch.
Miscellaneous
calc, funcs, server and xsdvalidate.
See Appendix A for an expanded version of this list.

There are many ways you might want to use these tools; here are a few possibilities:

In conjunction with TOPCAT
you can identify a set of processing steps using TOPCAT's interactive graphical facilities, and construct a script using the commands provided here which can perform the same steps on many similar tables without further user intervention.
Format conversion
If you have a separate table processing engine and you want to be able to output the results in a somewhat different form, for instance converting it from FITS to VOTable or from TABLEDATA-encoded to BINARY-encoded VOTable, or to perform some more scientifically substantial operation such as changing units or coordinate systems, substituting bad values etc, you can pass the results through one of the tools here. Since on the whole operation is streaming, such conversion can easily and efficiently be done on the fly.
Server-side operations
The tools provided here are suitable for use on servers, either to generate files as part of a web service (perhaps along the lines of the Format conversion item above) or as configurable components in a server-based workflow system. The server command may help, but is not required, for use in these situations.
Quick look
You might want to examine the metadata, or a few rows, or a statistical summary of a table without having to load the whole thing into TOPCAT or some other table viewer application.

## 2 The stilts command

All the functions available in this package can be used from a single command, which is usually referred to in this document simply as "stilts". Depending on how you have installed the package, you may just type "stilts", or something like

   java -jar some/path/stilts.jar

or
   java -classpath topcat-lite.jar uk.ac.starlink.ttools.Stilts

or something else - this is covered in detail in Section 3.

In general, the form of a command is

   stilts <stilts-flags> <task-name> <task-args>

The forms of the parts of this command are described in the following subsections, and details of each of the available tasks along with their arguments are listed in the command reference at the end of this document. Some of the commands are highly configurable and have a variety of parameters to define their operation. In many cases however, it's not complicated to use them. For instance, to convert the data in a FITS table to VOTable format you might write:
   stilts tcopy cat.fits cat.vot


### 2.1 Stilts flags

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. These generic flags are as follows:

-help
Prints a usage message for the stilts command itself and exits. The message contains a listing of all the known tasks.
-version
Prints the STILTS version number and exits.
-verbose
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 +verbose can be used to do the opposite (reduce the logging level by one notch).
-allowunused
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.
-prompt
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 -prompt 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.
-bench
Outputs the elapsed time taken by the task to standard error on successful completion.
-debug
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.
-batch
Some parameters will prompt you for their values, even if they offer legal defaults. If you use the -batch flag, then you won't be prompted at all.
-memory
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 -Dstartable.storage=memory.
-disk
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 -Dstartable.storage=disk.
-memgui
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.
-checkversion <vers>
Requires that the version is exactly as given by the string <vers>. 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.
-stdout <file>
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 "-" for <file> will restore this default behaviour.
-stderr <file>
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 "-" for <file> will restore this default behaviour.

If you are submitting an error report, please include the result of running stilts -version and the output of the troublesome command with the -debug flag specified.

The <task-name> part of the command line is the name of one of the tasks listed in Appendix B - currently the available tasks are:

• arrayjoin
• calc
• cdsskymatch
• cone
• coneskymatch
• datalinklint
• funcs
• pixfoot
• pixsample
• plot2cube
• plot2plane
• plot2sphere
• plot2sky
• plot2time
• plot2d
• plot3d
• plothist
• regquery
• server
• sqlclient
• sqlskymatch
• sqlupdate
• taplint
• tapquery
• tapresume
• tapskymatch
• tcat
• tcatn
• tcopy
• tcube
• tgridmap
• tjoin
• tloop
• tmatch1
• tmatch2
• tmatchn
• tmulti
• tmultin
• tpipe
• tskymap
• tskymatch2
• votcopy
• votlint
• xsdvalidate

The <task-args> part of the command line is a list of parameter assignments, each giving the value of one of the named parameters belonging to the task which is specified in the <task-name> part.

The general form of each parameter assignment is

   <param-name>=<param-value>

If you want to set the parameter to the null value, which is legal for some but not all parameters, use the special string "null", or just leave the value blank ("<param-name>="). In some cases you can optionally leave out the <param-name> part of the assignment (i.e. the parameter is positionally determined); this is indicated in the task's usage description if the parameter is described like [<param-name>=]<param-value> rather than <param-name>=<param-value>. If the <param-value> contains spaces or other special characters, then in most cases, such as from the Unix shell, you will have to quote it somehow. How this is done depends on your platform, but usually surrounding the whole value in single quotes will do the trick.

Tasks may have many parameters, and you don't have to set all of them explicitly on the comand line. For a parameter which you don't set, two things can happen. In many cases, it will default to some sensible value. Sometimes however, you may be prompted for the value to use. In the latter case, a line like this will be written to the terminal:

   matcher - Name of matching algorithm [sky]:

This is prompting you for the value of the parameter named matcher. "Name of matching algorithm" is a short description of what that parameter does. "sky" is the default value (if there is no default, no value will appear in square brackets). At this point you can do one of four things:
• Hit return - this will select the default value if there is one. If there is no default, this is equivalent to entering "null".
• Enter a value for the parameter explicitly. The special value "null" means the null value, which is legal for some, but not all parameters. If the value you enter is not legal, you will see an error message and you will be invited to try again.
• Enter "help" or a question mark "?". This will output a message giving a detailed description of the parameter and prompt you again.
• Bail out by hitting ctrl-C or whatever is usual on your platform.
Under normal circumstances, most parameters which have a legal default value will default to it if they are not set on the command line, and you will only be prompted for those where there is no default or the program thinks there's a good chance you might not want to use it. You can influence this however using flags to the stilts command itself (see Section 2.1). If you supply the -prompt flag, then you will be prompted for every parameter you have not explicitly set. If you supply -batch on the other hand, you won't be prompted for any parameters (and if you fail to set any without legal default values, the task will fail).

If you want to see the actual values of the parameters for a task as it runs, including prompted values and defaulted ones which you haven't specified explicitly, you can use the -verbose flag after the stilts command:

   % stilts -verbose tcopy cat.fits cat.vot ifmt=fits
INFO: tcopy in=cat.fits out=cat.vot ifmt=fits ofmt=(auto)


If you make a parameter assignment on the command line for a parameter which is not used by the task in question, STILTS will issue an error message and the task will fail. Note some parameters are only used dependent on the presence or values of other parameters, so even supplying a parameter which is documented in the task's usage can have this effect. This is done on the assumption that if you have supplied a spurious parameter it's probably a mistake and you should be given the opportunity to correct it. But if you want to be free to make these mistakes without the task failing, you can supply the -allowunused flag as described in Section 2.1, in which case they will just result in a warning.

Extensive help is available from stilts itself about task and its parameters, as described in the next section.

### 2.4 Getting Help

As well as the command descriptions in this document (especially the reference section Appendix B) you can get help for STILTS usage from the command itself. Typing

   stilts -help

results in this output:
   Usage:
stilts [-help] [-version] [-verbose] [-allowunused] [-prompt] [-bench]
[-debug] [-batch] [-memory] [-disk] [-memgui]
[-checkversion <vers>] [-stdout <file>] [-stderr <file>]

arrayjoin
calc
cdsskymatch
cone
coneskymatch
funcs
pixfoot
pixsample
plot2d
plot3d
plothist
regquery
server
sqlclient
sqlskymatch
sqlupdate
taplint
tapquery
tapresume
tapskymatch
tcat
tcatn
tcopy
tcube
tgridmap
tjoin
tloop
tmatch1
tmatch2
tmatchn
tmulti
tmultin
tpipe
tskymap
tskymatch2
votcopy
votlint
xsdvalidate
plot2plane
plot2sky
plot2cube
plot2sphere
plot2time


For help on the individual tasks, including their parameter lists, you can supply the word help after the task name, so for instance

   stilts tcopy help

results in
   Usage: tcopy ifmt=<in-format> ofmt=<out-format>
[in=]<table> [out=]<out-table>


Finally, you can get help on any of the parameters of a task by writing help=<param-name>, like this:

   stilts tcopy help=in

gives
   Help for parameter IN in task TCOPY
-----------------------------------

Name:
in

Usage:
[in=]<table>

Summary:
Location of input table

Description:
The location of the input table. This may take one of the following
forms:

* A filename.
* A URL.
* The special value "-", meaning standard input. In this case the
input format must be given explicitly using the ifmt parameter.
Note that not all formats can be streamed in this way.
* A scheme specification of the form :<scheme-name>:<scheme-args>.
* A system command line with either a "<" character at the start, or
a "|" character at the end ("<syscmd" or "syscmd|"). This
executes the given pipeline and reads from its standard output.
This will probably only work on unix-like systems.

In any case, compressed data in one of the supported compression
formats (gzip, Unix compress or bzip2) will be decompressed
transparently.

Type:

If you use "*" instead of a parameter name in this usage, help for all the parameters will be printed. Note that in most shells you will probably need to quote the asterisk, so you should write
   stilts tcopy help='*'


In some cases, as described in Section 2.3, you will be prompted for the value of a parameter with a line something like this:

   matcher - Name of matching algorithm [sky]:

In this case, if you enter "help" or a question mark, then the parameter help entry will be printed to the screen, and the prompt will be repeated.

For more detailed descriptions of the tasks, which includes explanatory comments and examples as well as the information above, see the full task descriptions in the Command Reference.

## 3 Invocation

There are a number of ways of invoking commands in the stilts application, depending on how you have installed the package. This section describes how to invoke it from the command line. Other options are using it from Jython (the Java implementation of the Python language) as described in Section 4, invoking it over HTTP as described in Section 11, and invoking it from within a Java application as described in Section 12.

If you're using a Unix-like operating system, the easiest way is to use the stilts script. If you have a full starjava installation it is in the starjava/bin directory. Otherwise you can download it separately from wherever you got your STILTS installation in the first place, or find it at the top of the stilts.jar or topcat-*.jar that contains your STILTS installation, so do something like

   unzip stilts.jar stilts
chmod +x stilts

to extract it (if you don't have unzip, try jar xvf stilts.jar stilts). stilts is a simple shell script which just invokes java with the right classpath and the supplied arguments.

To run using the stilts script, first make sure that both the java executable and the stilts script itself are on your path, and that the stilts.jar or topcat-*.jar jar file is in the same directory as stilts. Then the form of invocation is:

   stilts <java-flags> <stilts-flags> <task-name> <task-args>

A simple example would be:
   stilts votcopy format=binary t1.xml t2.xml

in this case, as often, there are no <java-flags> or <stilts-flags>. If you use the -classpath argument or have a CLASSPATH environment variable set, then classpath elements thus specified will be added to the classpath required to run the command. The examples in the command descriptions below use this form for convenience.

If you don't have a Unix-like shell available however, you will need to invoke Java directly with the appropriate classes on your classpath. If you have the file stilts.jar, in most cases you can just write:

   java <java-flags> -jar stilts.jar <stilts-flags> <task-name> <task-args>

which in practice would look something like
   java -jar /some/where/stilts.jar votcopy format=binary t1.xml t2.xml


In the most general case, Java's -jar flag might be no good, for one of the following reasons:

1. You have the classes in some form other than the stilts.jar file (such as topcat-full.jar)
2. You need to specify some extra classes on the classpath, which is required e.g. for use with JDBC or if you are extending the commands using your own classes at runtime
In this case, you will need an invocation of this form:
   java <java-flags> -classpath <class-path>

The example above in this case would look something like:
   java -classpath /some/where/topcat-full.jar uk.ac.starlink.ttools.Stilts
votcopy format=binary t1.xml t2.xml


Finally, as a convenience, it is possible to run STILTS from a TOPCAT installation by using its -stilts flag, like this:

   topcat <java-flags> -stilts <stilts-flags> <task-name> <task-args>

This is possible because TOPCAT is built on top of STILTS, so contains a superset of its code.

The <stilts-flags>, <task-name> and <task-args> parts of these invocations are explained in Section 2, and the <class-path> and <java-flags> parts are explained in the following subsections.

### 3.1 Class Path

The classpath is the list of places that Java looks to find the bits of compiled code that it uses to run an application. Depending on how you have done your installation the core STILTS classes could be in various places, but they are probably in a file with one of the names stilts.jar, topcat-lite.jar or topcat-full.jar. The full pathname of one of these files can therefore be used as your classpath. In some cases these files are self-contained and in some cases they reference other jar files in the filesystem - this means that they may or may not continue to work if you move them from their original location.

Under certain circumstances the tools might need additional classes, for instance:

In this case the classpath must contain a list of all the jar files in which the required classes can be found, separated by colons (unix) or semicolons (MS Windows). Note that even if all your jar files are in a single directory you can't use the name of that directory as a class path - you must name each jar file, separated by colons/semicolons.

### 3.2 Java Flags

In most cases it is not necessary to specify any additional arguments to the Java runtime, but it can be useful in certain circumstances. The two main kinds of options you might want to specify directly to Java are these:

System properties
System properties are a way of getting information into the Java runtime from the outside, rather like environment variables. There is a list of the ones which have significance to STILTS in Section 3.3. You can set them from the command line using a flag of the form -Dname=value. So for instance to ensure that temporary files are written to the /home/scratch directory, you could use the flag
   -Djava.io.tmpdir=/home/scratch

Memory size
Java runs with a fixed amount of 'heap' memory; this is typically 64Mb by default. If one of the tools fails with a message that says it's out of memory then this has proved too small for the job in hand. You can increase the heap memory with the -Xmx flag. To set the heap memory size to 256 megabytes, use the flag
   -Xmx256M

(don't forget the 'M' for megabyte). You will probably find performance is dreadful if you specify a heap size larger than the physical memory of the machine you're running on.

You can specify other options to Java such as tuning and profiling flags etc, but if you want to do that sort of thing you probably don't need me to tell you about it.

If you are using the stilts command-line script, any flags to it starting -D or -X are passed directly to the java executable. You can pass other flags to Java with the stilts script's -J flag; for instance:

   stilts -Xmx4M -J-verbose:gc calc 'mjdToIso(0)'

is equivalent to
   java -Xmx4M -verbose:gc -jar stilts.jar calc 'mjdToIso(0)'


### 3.3 System Properties

System properties are a way of getting information into the Java runtime - they are a bit like environment variables. There are two ways to set them when using STILTS: either on the command line using arguments of the form -Dname=value (see Section 3.2) or in a file in your home directory named .starjava.properties, in the form of a name=value line. Thus submitting the flag

   -Dvotable.strict=false

on the command line is equivalent to having the following in your .starjava.properties file:
   #  Force strict interpretation of the VOTable standard.
votable.strict=false


The following system properties have special significance to STILTS:

http.proxyHost
Can be used to force HTTP access to go via a named proxy; may be required if you are attempting access to remote data or services from behind a firewall configured to block direct HTTP connections. See java documentation for this property for more details.
java.awt.headless
May need to be set to "true" if running the plotting tasks on a headless server. You only need to worry about this if you see error messages complaining about headlessness.
java.io.tmpdir
The directory in which STILTS will write any temporary files it needs. This defaults to the system temporary directory (e.g. /tmp on Unix), so if working with large unmapped (e.g. CSV) tables on a machine with limited space on the default disk, it may be necessary to change it.
java.util.concurrent.ForkJoinPool.common.parallelism
Controls the level of parallelisation done by certain processing, currently mainly visualisation. By default it is typically set to one less than the number of processing cores on the current machine. To inhibit parallelisation (e.g. if you suspect that the parallel output is giving different results to sequential processing) you can set this to 1.
jdbc.drivers
Can be set to a (colon-separated) list of JDBC driver classes using which SQL databases can be accessed (see Section 3.4).
jel.classes
Can be set to a (colon-separated) list of classes containing static methods which define user-provided functions for synthetic columns or subsets. (see Section 10.8.3).
mark.workaround
If set to "true", this will work around a bug in the mark()/reset() methods of some java InputStream classes. These are rather common, including in Sun's J2SE system libraries. Use this if you are seeing errors that say something like "Resetting to invalid mark". Currently defaults to "false".
service.maxparallel
Raises the maximum number of concurrent queries that may be made during a multi-cone operation. You should only increase this value with great care since you risk overloading servers and becoming unpopular with data centres. As a rule, you should only increase this value if you have obtained permission from the data centres whose services on which you will be using the increased parallelism.
star.basicauth.user
star.basicauth.password
If set, these will provide username and password for HTTP Basic Authentication. Any time the application attempts to access an HTTP URL and is met by a 401 Unauthorized response, it will try again supplying these user credentials. This is a rather blunt instrument, since the same identity is supplied regardless of which URL is being accessed, but it may be of some use in accessing basic-authentication protected services.
startable.readers
Can be set to a (colon-separated) list of custom table format input handler classes (see SUN/252). Each class must implement the uk.ac.starlink.table.TableBuilder interface, and must have a no-arg constructor. The readers thus named will be available alongside the standard ones listed in Section 5.1.1.
startable.schemes
Can be set to a (colon-separated) list of custom table scheme handler classes. Each class must implement the uk.ac.starlink.table.TableScheme interface, and must have a no-arg constructor. The schemes thus named will be available alongside the standard ones listed in Section 5.3.
startable.storage
Can be set to determine the default storage policy. Setting it to "disk" has basically the same effect as supplying the "-disk" argument on the command line (see Section 2.1). Other possible values are "adaptive", "memory", "sideways" and "discard"; see SUN/252. The default is "adaptive", which means storing smaller tables in memory, and larger ones on disk.
startable.unmap
Determines whether and how unmapping of memory mapped buffers is done. Possible values are "sun" (the default), "cleaner", "unsafe" or "none". In most cases you are advised to leave this alone, but in the event of unmapping-related JVM crashes (not expected!), setting it to none may help.
startable.writers
Can be set to a (colon-separated) list of custom table format output handler classes (see SUN/252). Each class must implement the uk.ac.starlink.table.StarTableWriter interface, and must have a no-arg constructor. The writers thus named will be available alongside the standard ones listed in Section 5.1.2.
votable.namespacing
Determines how namespacing is handled in input VOTable documents. Known values are "none" (no namespacing, xmlns declarations in VOTable document will probably confuse parser), "lax" (anything that looks like it is probably a VOTable element will be treated as a VOTable element) and "strict" (VOTable elements must be properly declared in one of the correct VOTable namespaces). May also be set to the classname of a uk.ac.starlink.votable.Namespacing implementation. The default is "lax".
votable.strict
Controls the behaviour when encountering a VOTable FIELD or PARAM element with a datatype attribute of char/unicodeChar, and no arraysize attribute. The VOTable standard says this indicates a single character, but some VOTables omit arraysize specification by accident when they intend arraysize="*". If votable.strict is set true, a missing arraysize will be interpreted as meaning a single character, and if false, it will be interpreted as a variable-length array of characters (a string). The default is true.
votable.version
Selects the version of the VOTable standard which output VOTables will conform to by default. May take the values "1.0", "1.1", "1.2", "1.3" or "1.4". By default, version 1.4 VOTables are written.

### 3.4 JDBC Configuration

This section describes additional configuration which must be done to allow the commands to access SQL-compatible relational databases for reading or writing tables. If you don't need to talk to SQL-type databases, you can ignore the rest of this section. The steps described here are the standard ones for configuring JDBC (which sort-of stands for Java Database Connectivity); you can find more information on that on the web. The best place to look may be within the documentation of the RDBMS you are using.

To use STILTS with SQL-compatible databases you must:

• Have access to an SQL-compatible database locally or over the network
• Have a JDBC driver appropriate for that database
• Install that driver for use with STILTS
• Know the format the driver uses for URLs to access database tables
• Have appropriate privileges on the database to perform the desired operations
Installing the driver consists of two steps:
1. Ensure that the classpath you are using includes this driver class as described in Section 3.1
2. Set the jdbc.drivers system property to the name of the driver class as described in Section 3.3

Here is an example of using tpipe to write the results of an SQL query on a table in a MySQL database as a VOTable:

   stilts -classpath /usr/local/jars/mysql-connector-java.jar \
-Djdbc.drivers=com.mysql.jdbc.Driver \
tpipe \
in="jdbc:mysql://localhost/db1#SELECT id, ra, dec FROM gsc WHERE mag < 9" \
ofmt=votable gsc.vot

or invoking Java directly:
   java -classpath stilts.jar:/usr/local/jars/mysql-connect-java.jar \
-Djdbc.drivers=com.mysql.jdbc.Driver \
in="jdbc:mysql://localhost/db1#SELECT id, ra, dec FROM gsc WHERE mag < 9" \
ofmt=votable out=gsc.vot

You have to exercise some care to get the arguments in the right order here - see Section 3.

Alternatively, you can set some of this up beforehand to make the invocation easier. If you set your CLASSPATH environment variable to include the driver jar file (and the STILTS classes if you're invoking Java directly rather than using the scripts), and if you put the line

   jdbc.drivers=com.mysql.jdbc.Driver

in the .starjava.properties file in your home directory, then you could avoid having to give the -classpath and -Djdbc.drivers flags respectively.

Below are presented the results of some experiments with JDBC drivers. Note however that this information may be be incomplete and out of date. If you have updates, feel free to pass them on and they may be incorporated here.

To the author's knowledge, STILTS has successfully been used with the following RDBMSs and corresponding JDBC drivers:

MySQL
MySQL has been tested on Linux with the Connector/J driver and seems to work; tested versions are server 3.23.55 with driver 3.0.8 and server 4.1.20 with driver 5.0.4. Sometimes tables with very many (hundreds of) columns cannot be written owing to SQL statement length restrictions. Note there is known to be a column metadata bug in version 3.0.6 of the driver which can cause a ClassCastException error when tables are written. Check the driver's documentation for additional parameters, for instance "useUnicode=true&characterEncoding=UTF8" may be required to handle some non-ASCII characters.
PostgreSQL
PostgreSQL 7.4.1 apparently works with its own driver. Note the performance of this driver appears to be rather poor, at least for writing tables.
Oracle
You can use Oracle with the JDBC driver that comes as part of its Basic Instant Client Package.
SQL Server
There is more than one JDBC driver known to work with SQL Server, including jTDS and its own JDBC driver. Some evidence suggests that jTDS may be the better choice, but your mileage may vary.
Sybase ASE
There has been a successful use of Sybase 12.5.2 and jConnect (jconn3.jar) using a JDBC URL like "jdbc:sybase:Tds:hostname:port/dbname?user=XXX&password=XXX#SELECT...". An earlier attempt using Sybase ASE 11.9.2 failed.
It is probably possible to use other RDBMSs and drivers, but you may have to do some homework.

Here are some example command lines that at least have at some point got STILTS running with databases:

PostgreSQL
   stilts -classpath pg73jdbc3.jar \
-Djdbc.drivers=org.postgresql.Driver ...

MySQL
   stilts -classpath mysql-connector-java-3.0.8-bin.jar \
-Djdbc.drivers=com.mysql.jdbc.Driver ...

Oracle
   stilts -classpath ojdbc14.jar \
-Djdbc.drivers=oracle.jdbc.driver.OracleDriver ...

SQL Server with jTDS
   stilts -classpath jtds-1.1.jar \
-Djdbc.drivers=net.sourceforge.jtds.jdbc.Driver ...


## 4 JyStilts - STILTS from Python

Most of the discussions and examples in this document describe using STILTS as a standalone java application from the command line; in this case, scripting can be achieved by executing one STILTS command, followed by another, followed by another, perhaps controlled from a shell script, with intermediate results stored in files.

However, it is also possible to invoke STILTS commands from within the Jython environment. Jython is a pure-java implementation of the widely-used Python scripting language. Using Jython is almost exactly the same as using the more usual C-based Python, except that it is not possible to use extensions which use C code. This means that if you are familiar with Python programming, it is very easy to string STILTS commands together in Jython.

This approach has several advantages over the conventional command-line usage:

• You can make use of python programming constructions like loops, functions and variables
• Python syntax can be used to put together parameter values (especially referencing quoted strings or values containing embedded spaces) in a way which is often less painful than doing it from the shell
• Intermediate processing stages can be kept in memory (in a python variable) rather than having to write them out to a file and read them in for the next command; this can be much more efficient
• Because of the previous point, there are separate read, filter, processing and write commands, which means command lines can be shorter and less confusing
• The java startup overhead (typically a couple of seconds) happens only once when entering jython, not once for every STILTS command
Note however that you will not be able to introduce JyStilts commands into your larger existing Python programs if those rely on C-based extensions, such as NumPy and SciPy, since JyStilts will only run in JPython, while C-based extensions will only run in CPython. (See however JNumeric for some of the Numpy functionality from Jython.)

Usage from jython has syntax which is similar to command-line STILTS, but with a few changes. The following functions are defined by JyStilts:

• A function tread, which reads a table from a file or URL and turns it into a table object in jython
• A table method write which takes a table object and writes it to file
• A table method for each STILTS filter (e.g. cmd_head, cmd_select, cmd_addcol)
• A table method for each STILTS output mode (e.g. mode_out, mode_meta, mode_samp),
• A function for each STILTS task (e.g. tmatch2, tcat, plot2sky)
• A number of table methods which make table objects integrate nicely into the python environment
Reasonably detailed documentation for these is provided in the usual Python way ("doc strings"), and can be accessed using the Python "help" command, however for full documentation and examples you should refer to this document.

In JyStilts the input, processing, filtering and output are done in separate steps, unlike in command-line STILTS where they all have to be combined into a single line. This can make the flow of execution easier to follow. A typical sequence will involve:

1. Reading one or more tables from file using the tread function
2. Perhaps filtering the input table(s) using one or more of the cmd_* filter methods
3. Performing core processing such as crossmatching
4. Perhaps filtering the result using one or more of the cmd_* filter methods
5. If running interactively, perhaps examining the intermediate results using one of the mode_* output modes
6. Writing the final result to a file using the write method

Here is an example command line invocation for crossmatching two tables:

stilts tskymatch2 in1=survey.fits \
icmd1='addskycoords fk4 fk5 RA1950 DEC1950 RA2000 DEC2000' \
in2=mycat.csv ifmt2=csv \
icmd2='select VMAG>18' \
ra1=ALPHA dec1=DELTA ra2=RA2000 dec2=DEC2000 \
error=10 join=2not1 \
out=matched.fits

and here is what it might look like in JyStilts:
>>> import stilts
>>> t1 = t1.cmd_addskycoords(t1, 'fk4', 'fk5', 'RA1950', 'DEC1950', 'RA2000', 'DEC2000')
>>> t2 = t2.cmd_select('VMAG>18')
>>> tm = stilts.tskymatch2(in1=t1, in2=t2, ra1='ALPHA', dec1='DELTA',
...                        error=10, join='2not1')
>>> tm.write('matched.fits')


When running interactively, it can be convenient to examine the intermediate results before processing or writing as well, for instance:

>>> tm.mode_count()
columns: 19   rows: 2102
+--------+---------------+-----------+
| ID     | ALPHA         | DELTA     |
+--------+---------------+-----------+
| 262    | 149.82439     | -0.11249  |
| 263    | 150.14438     | -0.11785  |
| 265    | 149.92944     | -0.11667  |
| 273    | 149.93185     | -0.12566  |
+--------+---------------+-----------+


More detail about how to run JyStilts and its usage is given in the following subsections.

### 4.1 Running JyStilts

The easiest way to run JyStilts is to download the standalone jystilts.jar file from the STILTS web page, and simply run

java -jar jystilts.jar

This file includes jython itself and all the STILTS and JyStilts classes. To use the JyStilts commands, you will need to import the stilts module using a line like "import stilts" from Jython in the usual Python way.

Alternatively, you can run JyStilts from an existing Jython installation using just the stilts.jar file. First, make sure that Jython is installed; it is available from http://www.jython.org/, and comes as a self-installing jar file. JyStilts has been tested, and appears to work, with jython version 2.7.2. It also works with jython 2.5.* under Java 8 and Java 11, but jystilts with jython 2.5.* and Java 17 can fail with security problems. Some earlier versions of JyStilts worked with jython 2.2.1, but that no longer seems to be the case; it might be possible to reinstate this if there is some pressing need.

To use JyStilts, you then just need to start jython with the stilts.jar file on your classpath, for instance like this:

jython -J-classpath /some/where/stilts.jar

or (C-shell):
setenv CLASSPATH /some/where/stilts.jar
jython


#### 6.1.31 sort

Usage:

   sort [-down] [-nullsfirst] [-[no]parallel] <key-list>

Sorts the table according to the value of one or more algebraic expressions. The sort key expressions appear, as separate (space-separated) words, in <key-list>; sorting is done on the first expression first, but if that results in a tie then the second one is used, and so on.

Each expression must evaluate to a type that it makes sense to sort, for instance numeric. If the -down flag is used, the sort order is descending rather than ascending.

Blank entries are by default considered to come at the end of the collation sequence, but if the -nullsfirst flag is given then they are considered to come at the start instead.

By default, sorting is done sequentially for small tables and in parallel for large tables, but this can be controlled with the -parallel or -noparallel flag.

Syntax for the <key-list> argument is described in Section 10.

#### 6.1.32 sorthead

Usage:

   sorthead [-tail] [-down] [-nullsfirst] <nrows> <key-list>

Performs a sort on the table according to the value of one or more algebraic expressions, retaining only <nrows> rows at the head of the resulting sorted table. The sort key expressions appear, as separate (space-separated) words, in <key-list>; sorting is done on the first expression first, but if that results in a tie then the second one is used, and so on. Each expression must evaluate to a type that it makes sense to sort, for instance numeric.

If the -tail flag is used, then the last <nrows> rows rather than the first ones are retained.

If the -down flag is used the sort order is descending rather than ascending.

Blank entries are by default considered to come at the end of the collation sequence, but if the -nullsfirst flag is given then they are considered to come at the start instead.

This filter is functionally equivalent to using sort followed by head, but it can be done in one pass and is usually cheaper on memory and faster, as long as <nrows> is significantly lower than the size of the table.

Syntax for the <key-list> argument is described in Section 10.

#### 6.1.33 stats

Usage:

   stats [-[no]parallel] [-qapprox|-qexact] [<item> ...]

Calculates statistics on the data in the table. This filter turns the table sideways, so that each row of the output corresponds to a column of the input. The columns of the output table contain statistical items such as mean, standard deviation etc corresponding to each column of the input table.

By default the output table contains columns for the following items:

• Name: Column name
• Mean: Average
• StDev: Population Standard deviation
• Minimum: Numeric minimum
• Maximum: Numeric maximum
• NGood: Number of non-blank cells

However, the output may be customised by supplying one or more <item> headings. These may be selected from the above as well as the following:

• NBad: Number of blank cells
• Variance: Population Variance
• SampStDev: Sample Standard Deviation
• SampVariance: Sample Variance
• MedAbsDev: Median Absolute Deviation
• ScMedAbsDev: Median Absolute Deviation * 1.4826
• Skew: Gamma 1 skewness measure
• Kurtosis: Gamma 2 peakedness measure
• Sum: Sum of values
• MinPos: Row index of numeric minimum
• MaxPos: Row index of numeric maximum
• Cardinality: Number of distinct values in column; values >100 ignored
• Median: Middle value in sequence
• Quartile1: First quartile
• Quartile2: Second quartile
• Quartile3: Third quartile
• ArrayNGood: Per-element non-blank counts for fixed-length array columns
• ArraySum: Per-element sums for fixed-length array columns
• ArrayMean: Per-element means for fixed-length array columns
• ArrayStDev: Per-element population standard deviation for fixed-length array columns
Additionally, the form "Q.nn" may be used to represent the quantile corresponding to the proportion 0.nn, e.g.:
• Q.25: First quartile
• Q.625: Fifth octile

Any parameters of the input table are propagated to the output one.

The -qapprox or -qexact flag controls how quantiles are calculated. With -qexact they are calculated exactly, but this requires memory usage scaling with the number of rows. If the -qapprox flag is supplied, an method is used which is typically slower and produces only approximate values, but which will work in fixed memory and so can be used for arbitrarily large tables. By default, exact calculation is used. These flags are ignored if neither quantiles nor the MAD are being calculated

The -noparallel flag may be supplied to inhibit multi-threaded statistics accumulation. Calculation is done in parallel by default if multi-threaded hardware is available, and it's usually faster.

#### 6.1.34 tablename

Usage:

   tablename <name>

Sets the table's name attribute to the given string.

#### 6.1.35 tail

Usage:

   tail <nrows>

Include only the last <nrows> rows of the table. If the table has fewer than <nrows> rows then it will be unchanged.

#### 6.1.36 transpose

Usage:

   transpose [-namecol <col-id>]

Transposes the input table so that columns become rows and vice versa. The -namecol flag can be used to specify a column in the input table which will provide the column names for the output table. The first column of the output table will contain the column names of the input table.

Syntax for the <col-id> argument is described in Section 6.2.

#### 6.1.37 uniq

Usage:

   uniq [-count] [<colid-list>]

Eliminates adjacent rows which have the same values. If used with no arguments, then any row which has identical values to its predecessor is removed.

If the <colid-list> parameter is given then only the values in the specified columns must be equal in order for the row to be removed.

If the -count flag is given, then an additional column with the name DupCount will be prepended to the table giving a count of the number of duplicated input rows represented by each output row. A unique row has a DupCount value of 1.

Syntax for the <colid-list> argument is described in Section 6.3.

### 6.2 Specifying a Single Column

If an argument is specified in the help text for a command with the symbol <col-id> it means you must give a string which identifies one of the existing columns in a table.

There are several ways you can specify a column in this context:

Column Name
The name of the column may be used if it contains no spaces. It is usually matched case insensitively. If multiple columns have the same name, the first one that matches is selected.
Column Index or $ID The index of the column may always be used; this is a useful fallback if the column name isn't suitable for some reason. The first column is '1', the second is '2' and so on. You may alternatively use the forms '$1', '$2' etc. Tip: if counting which column has which index is giving you a headache, running tpipe with omode=meta or omode=stats on the table may help. Column ucd$ specifier
If the column has a Unified Content Descriptor (this will usually only be the case for VOTable or possibly FITS format tables) you can refer to it using an identifier of the form "ucd$<ucd-spec>". Depending on the version of UCD scheme used, UCDs can contain various punctuation marks such as underscores, semicolons and dots; for the purpose of this syntax these should all be represented as underscores ("_"). So to identify a column which has the UCD "phot.mag;em.opt.R", you should use the identifier "ucd$phot_mag_em_opt_r". Matching is not case-sensitive. Futhermore, a trailing underscore acts as a wildcard, so that the above column could also be referenced using the identifier "ucd$phot_mag_". If multiple columns have UCDs which match the given identifer, the first one will be used. Column utype$ specifier
If the column has a Utype (this will usually only be the case for VOTable or possibly FITS format tables) you can refer to it using an identifier of the form "utype$<utype-spec>". Utypes may contain various punctuation marks such as colons and dots; for the purpose of this syntax these should all be represented as underscores ("_"). So to identify a column which has the Utype "ssa:Access.Format", you should use the identifier "utype$ssa_Access_format". Matching is not case-sensitive. If multiple columns have Utypes which match the given identifier, the first one will be used.

### 6.3 Specifying a List of Columns

If an argument is specified in the help text for a command with the symbol <colid-list> it means you must give a string which identifies a list of zero, one or more of the existing columns in a table. The string you specify is a separated into separate tokens by whitespace, which means that you will normally have to surround it in single or double quotes to ensure that it is treated as a single argument and not several of them.

Each token in the <colid-list> string may be one of the following:

Single Column Identifier
The identifier for a single column, as described in Section 6.2: one of <name>, <index>, $<index>, ucd$<ucd-expr> or utype$<utype-expr>. Wildcard Expression You can use a simple form of wildcard expression which expands to any columns in the table whose names match the pattern. Currently, the only special character is an asterisk '*' which matches any sequence of characters. To match an unknown sequence at the start or end of the string an asterisk must be given explicitly. Other than that, matching is usually case insensitive. The order of the expanded list is the same as the order in which the columns appear in the table. Thus "col*" will match columns named col1, Column2 and COL_1024, but not decOld. "*MAG*" will match columns named magnitude, ABS_MAG_U and JMAG. "*" on its own expands to a list of all the columns of the table in order. Column Range You can specify a range of columns in order using a token of the form <first-colid>-<last-colid>, where the syntax for <first-colid> and <last-colid> is a Single Column Identifier as above (as long as it doesn't contain a "-" character). The range is inclusive, so the first and last column are both included. The <first-colid> or <last-colid> part (but not both) may be omitted, to indicate all the columns from the start or all the columns to the end, respectively. So "RA-PARALLAX" means all the columns starting with the one named RA and ending with the one named PARALLAX (inclusive); "1-100" or "$1-$100" means the first hundred columns in the table; "101-" or "$101-" means all the columns apart from the first hundred, "PARALLAX-" means PARALLAX and all subsequent columns, etc.

Specifying a list which contains a given column more than once is not usually an error, but what effect it has depends on the function you are executing.

### 6.4 Output Modes

This section lists the output modes which can be used as the value of the omode parameter of tpipe and other commands. Typically, having produced a result table by pipeline processing an input one, you will write it out by specifying omode=out (or not using the omode parameter at all - out is the default). However, you can do other things such as calculate statistics, display metadata, etc. In some of these cases, additional parameters are required. The different output modes, with their associated parameters, are described in the following subsections.

#### 6.4.1 cgi

Usage:

   omode=cgi ofmt=<out-format>


Writes a table to standard output in a way suitable for use as output from a CGI (Common Gateway Interface) program. This is very much like out mode but a short CGI header giving the MIME Content-Type is prepended to the output

Additional parameters for this output mode are:

ofmt = <out-format>       (String)
Specifies the format in which the output table will be written (one of the ones in Section 5.1.2 - matching is case-insensitive and you can use just the first few letters).

[Default: votable]

#### 6.4.2 checksum

Usage:

   omode=checksum


Calculates a checksum from all the data in the table. The checksum is written to standard output in hexadecimal; row and column counts are also written.

If two tables have the same checksum it is extremely likely that they contain the same cell data. If they have a different checksum, their cell data differs. By default, the checksum implementation uses Adler32, which is fast but not cryptographically secure.

#### 6.4.3 count

Usage:

   omode=count


Counts the number of rows and columns and writes the result to standard output.

#### 6.4.4 discard

Usage:

   omode=discard


Reads all the data in the table in sequential mode and discards it. May be useful in conjunction with the assert filter.

#### 6.4.5 gui

Usage:

   omode=gui


Displays the table in a scrollable window.

#### 6.4.6 meta

Usage:

   omode=meta


Prints the table metadata to standard output. The name and type etc of each column is tabulated, and table parameters are also shown.

See the meta filter for more flexible output of table metadata.

#### 6.4.7 out

Usage:

   omode=out out=<out-table> ofmt=<out-format>


Writes a new table.

Additional parameters for this output mode are:

out = <out-table>       (TableConsumer)
The location of the output table. This is usually a filename to write to. If it is equal to the special value "-" (the default) the output table will be written to standard output.

[Default: -]

ofmt = <out-format>       (String)
Specifies the format in which the output table will be written (one of the ones in Section 5.1.2 - matching is case-insensitive and you can use just the first few letters). If it has the special value "(auto)" (the default), then the output filename will be examined to try to guess what sort of file is required usually by looking at the extension. If it's not obvious from the filename what output format is intended, an error will result.

[Default: (auto)]

#### 6.4.8 plastic

Usage:

   omode=plastic transport=string|file client=<app-name>


Broadcasts the table to any registered Plastic-aware applications. PLASTIC, the PLatform for AStronomical Tool InterConnection, is a tool interoperability protocol. A Plastic hub must be running in order for this to work.

Additional parameters for this output mode are:

transport = string|file       (String)
Determines the method (PLASTIC message) used to perform the PLASTIC communication. The choices are
• string: VOTable serialized as a string and passed as a call parameter (ivo://votech.org/votable/load). Not suitable for very large files.
• file: VOTable written to a temporary file and the filename passed as a call parameter (ivo://votech.org/votable/loadFromURL). The file ought to be deleted once it has been loaded. Not suitable for inter-machine communication.
If no value is set (null) then a decision will be taken based on the apparent size of the table.
client = <app-name>       (String)
Gives the name of a PLASTIC listener application which is to receive the broadcast table. If a non-null value is given, then only the first registered application which reports its application name as that value will receive the message. If no value is supplied, the broadcast will be to all listening applications.

#### 6.4.9 samp

Usage:

   omode=samp format=<value> client=<name-or-id>


Sends the table to registered SAMP-aware applications subscribed to a suitable table load MType. SAMP, the Simple Application Messaging Protocol, is a tool interoperability protocol. A SAMP Hub must be running for this to work.

Additional parameters for this output mode are:

format = <value>       (String[])
Gives one or more table format types for attempting the table transmission over SAMP. If multiple values are supplied, they should be separated by spaces. Each value supplied for this parameter corresponds to a different MType which may be used for the transmission. If a single value is used, a SAMP broadcast will be used. If multiple values are used, each registered client will be interrogated to see whether it subscribes to the corresponding MTypes in order; the first one to which it is subscribed will be used to send the table. The standard options are
• votable: use MType table.load.votable
• fits: use MType table.load.fits
If any other string is used which corresponds to one of STILTS's known table output formats, an attempt will be made to use an ad-hoc MType of the form table.load.format.

[Default: votable fits]

client = <name-or-id>       (String)
Identifies a registered SAMP client which is to receive the table. Either the client ID or the (case-insensitive) application name may be used. If a non-null value is given, then the table will be sent to only the first client with the given name or ID. If no value is supplied the table will be sent to all suitably subscribed clients.

#### 6.4.10 stats

Usage:

   omode=stats


Calculates and displays univariate statistics for each of the numeric columns in the table. The following entries are shown for each column as appropriate:

• mean
• population standard deviation
• minimum
• maximum
• number of non-null entries

See the stats filter for more flexible statistical calculations.

#### 6.4.11 topcat

Usage:

   omode=topcat


Attempts to display the output table directly in TOPCAT. If a TOPCAT instance is already running on the local host, an attempt will be made to open the table in that. A variety of mechanisms are used to attempt communication with an existing TOPCAT instance. In order:

1. SAMP using existing hub (TOPCAT v3.4+ only, requires SAMP hub to be running)
2. PLASTIC using existing hub (requires PLASTIC hub to be running)
3. SOAP (requires TOPCAT to run with somewhat deprecated -soap flag, may be limitations on table size)
4. SAMP using internal, short-lived hub (TOPCAT v3.4+ only, running hub not required, but may be slow. It's better to start an external hub, e.g. topcat -exthub)
Failing that, an attempt will be made to launch a new TOPCAT instance for display. This only works if the TOPCAT classes are on the class path.

If large tables are involved, starting TOPCAT with the -disk flag is probably a good idea.

#### 6.4.12 tosql

Usage:

   omode=tosql protocol=<jdbc-protocol> host=<value> db=<db-name>
dbtable=<table-name> write=create|dropcreate|append


Writes a new table to an SQL database. You need the appropriate JDBC drivers and -Djdbc.drivers set as usual (see Section 3.4).

Additional parameters for this output mode are:

protocol = <jdbc-protocol>       (String)
The driver-specific sub-protocol specifier for the JDBC connection. For MySQL's Connector/J driver, this is mysql, and for PostgreSQL's driver it is postgresql. For other drivers, you may have to consult the driver documentation.
host = <value>       (String)
The host which is acting as a database server.

[Default: localhost]

db = <db-name>       (String)
The name of the database on the server into which the new table will be written.

The value of this parameter forms the last part of the JDBC connection URL. That means that for some JDBC drivers, you can append parameter specifications to it to affect the way the connection is made to the database, e.g. "db=some_db?useSSL=false" for MySQL's Connector/J.

dbtable = <table-name>       (String)
The name of the table which will be written to the database.
write = create|dropcreate|append       (WriteMode)
Controls how the values are written to a table in the database. The options are:
• create: Creates a new table before writing. It is an error if a table of the same name already exists.
• dropcreate: Creates a new database table before writing. If a table of the same name already exists, it is dropped first.
• append: Appends to an existing table. An error results if the named table has the wrong structure (number or types of columns) for the data being written.

[Default: create]

user = <username>       (String)
User name for the SQL connection to the database.

[Default: mbt]

password = <passwd>       (String)
Password for the SQL connection to the database.

## 7 Crossmatching

STILTS offers flexible and efficient facilities for crossmatching tables. Crossmatching is identifying different rows, which may be in the same or different tables, that refer to the same item. In an astronomical context such an item is usually, though not necessarily, an astronomical source or object. This operation corresponds to what in database terminology is called a join.

There are various complexities to specifying such a match. In the first place you have to define what is the condition that must be satisfied for two rows to be considered matching. In the second place you must decide what happens if, for a given row, more than one match can be found. Finally, you have to decide what to do having worked out what the matched rows are; the result will generally be presented as a new output table, but there are various choices about what columns and rows it will consist of. Some of these issues are discussed in this section, and others in the reference sections on the tools themselves in Appendix B.

Matching can in general be a computationally intensive process. The algorithm used by the tmatch* tasks in STILTS, except in pathological cases, scales as O(N log(N)) or thereabouts, where N is the total number of rows in all the tables being matched. No preparation (such as sorting) is required on the tables prior to invoking the matching operation. It is reasonably fast; for instance an RA, Dec positional match of two 105-row catalogues takes of the order of 60 seconds on current (2005 laptop) hardware. Attempting matches with large tables can lead to running out of memory; the calculation just mentioned required a java heap size of around 200Mb (-Xmx200M).

In the current release of STILTS the following tasks are provided for crossmatching between local tables:

tmatch2
Generic crossmatching between two tables.
tskymatch2
Crossmatching between two tables where the matching criterion is a fixed separation on the sky. This is simply a stripped-down version of tmatch2 provided for convenience when the full generality is not required.
tmatch1
Generic crossmatching internal to a single table. The basic task this performs is to identify groups of rows within a single table which match each other.
tmatchn
Generic crossmatching between multiple (>2) tables.
tjoin
Trivial join operation between multiple tables in which no row re-ordering is required. This barely warrants the term "crossmatch" and the concepts explained in the rest of this section are not relevant to it.

### 7.1 Match Criteria

Determining whether one row represents the same item as another is done by comparing the values in certain of their columns to see if they are the same or similar. The most common astronomical case is to say that two rows match if their celestial coordinates (right ascension and declination) are within a given small radius of each other on the sky. There are other possibilities; for instance the coordinates to compare may be in a Cartesian space, or have a higher (or lower) dimensionality than two, or the match may be exact rather than within an error radius....

If you just need to match two tables according to sky position with fixed errors you are recommended to use the simplified tskymatch2 task. For other cases, this section describes how to specify much more flexible match criteria for use with tmatch1, tmatch2 or tmatchn by setting the following parameters:

matcher
Name of the match criteria type.
params
Fixed value(s) giving the parameters of the match (typically an error radius). If more than one value is required, the values should be separated by spaces.
values*
Expressions to be compared between rows. This will typically contain the names of one or more columns, but each element may be an algebraic expression (see Section 10) rather than just a column name if required. If more than one value is required, the values should be separated by spaces. There is one of these parameters for each table taking part in the match, so for tmatch2 you must specify both values1 and values2.
tuning
Fixed value(s) supplying tuning parameters for the match algorithm. If there is more than one value, they should be separated by spaces. This value will have a sensible default, so you do not need to supply it, but providing adjusted values may make your match run faster or require less memory (or the reverse). Adjusting tuning parameters will not change the result of any match, only the resources required to run it. Looking at the progress output of a match will indicate what tuning values have been used; adjusting the value a bit up or down is a good way to experiment.

For example, suppose we wish to locate objects in two tables which are within 3 arcseconds of each other on the sky. One table has columns RA and DEC which give coordinates in degrees, and the other has columns RArad and DECrad which give coordinates in radians. These are the arguments which would be used to tell tmatch2 what the match criteria are:

   matcher=sky
params=3
values1='RA DEC'

It is clearly important that corresponding values are comparable (in the same units) between the tables being matched, and in geometrically sensitive cases such as matching on the sky, it's important that they are the units expected by the matcher as well. To determine what those units are, either consult the roster below, or run the following command:
   stilts tmatch2 help=matcher

which will tell you about all the known matchers and their associated params, values* and tuning parameters.

The following subsections list the basic matcher types and the requirements of their associated params, values* and tuning parameters. The units of the required values are given where significant.

#### 7.1.1 sky: Sky Matching

matcher=sky values*='<ra/degrees> <dec/degrees>'
params='<max-error/arcsec>'
tuning='<healpix-k>'
values*:
• ra/degrees: Right Ascension
• dec/degrees: Declination
params:
• max-error/arcsec: Maximum separation along a great circle
tuning:
• healpix-k: Controls sky pixel size. Legal range 0 - 29. 0 is 60deg, 20 is 0.2".

The sky matcher compares positions on the celestial sphere with a fixed error radius. Rows are considered to match when the two (ra, dec) positions are within max-error arcseconds of each other along a great circle.

In fact this matching is not restricted to equatorial coordinates - the ra and dec parameters may represent any longitude-like and latitude-like coordinates in degrees, since the spherical geometry for the matching is unchanged under such transformations.

#### 7.1.2 skyerr: Sky Matching with Per-Object Errors

matcher=skyerr values*='<ra/degrees> <dec/degrees> <error/arcsec>'
params='<scale/arcsec>'
tuning='<healpix-k>'
values*:
• ra/degrees: Right Ascension
• dec/degrees: Declination
• error/arcsec: Per-object error radius along a great circle
params:
• scale/arcsec: Rough average of per-object error distance; just used for tuning to set default pixel size
tuning:
• healpix-k: Controls sky pixel size. Legal range 0 - 29. 0 is 60deg, 20 is 0.2".

The skyerr matcher compares positions on the celestial sphere using error radii which can be different for each row. Rows are considered to match when the separation between the two ra, dec positions is no larger than the sum of the two per-row error values.

The scale parameter should be a rough average value of the error distances. It is used only to set a sensible default for healpix-k tuning parameter, and its value does not affect the result. If you set healpix-k directly, its value is ignored.

As with sky matching, other longitude/latitude coordinate pairs may be used in place of right ascension and declination.

Note: the semantics of this matcher have changed slightly at version 2.4 of STILTS. In earlier versions the single parameter was named max-error and provided an additional constraint on the maximum accepted separation between matched objects. For most uses, the old and new behaviours are expected to give the same results, but in cases of difference, the new behaviour is more likely what you want.

#### 7.1.3 skyellipse: Sky Matching of Elliptical Regions

matcher=skyellipse values*='<ra/degrees> <dec/degrees> <primary-radius/arcsec>
<position-angle/degrees>'
params='<scale/arcsec>'
tuning='<healpix-k>'
values*:
• ra/degrees: Right ascension of centre
• dec/degrees: Declination of centre
• primary-radius/arcsec: Length of ellipse semi-major axis
• secondary-radius/arcsec: Length of ellipse semi-minor axis
• position-angle/degrees: Position angle - measured from north pole to primary axis, in direction of positive RA
params:
• scale/arcsec: Rough average of ellipse major radius; just used for tuning to set default pixel size
tuning:
• healpix-k: Controls sky pixel size. Legal range 0 - 29. 0 is 60deg, 20 is 0.2".

The skyellipse matcher compares elliptical regions on the sky for overlap. Each row has to provide five values, giving the centre, the major and minor radii, and the position angle of an ellipse. Rows are considered to match if there is any overlap between the ellipses. The goodness of match is a normalised generalisation of the symmetrical case used by the skyerr matcher, in which the best possible match is two concentric ellipses, and the worst allowable match is when the circumferences just touch.

The calculations are approximate since in some cases they rely on projecting the ellipses onto a Cartesian tangent plane before evaluating the match, so for larger ellipses the criterion will be less exact. For objects the size of most observed stars or galaxies, this approximation is not expected to be problematic.

The scale parameter must be supplied, and should be a rough average value of the major radii. it is used only to set a sensible default for the healpix-k tuning parameter, and its value does not affect the result. If you set healpix-k directly, the value of scale is ignored.

#### 7.1.4 sky3d: Spherical Polar Matching

matcher=sky3d values*='<ra/degrees> <dec/degrees> <distance>'
params='<error/units of distance>'
tuning='<bin-factor>'
values*:
• ra/degrees: Right Ascension
• dec/degrees: Declination
• distance: Distance from origin
params:
• error/units of distance: Maximum Cartesian separation for match
tuning:
• bin-factor: Scaling factor to adjust bin size; larger values mean larger bins

The sky3d matcher compares positions in the volume of the sky taking account of distance from the observer. The position in three-dimensional space is calculated for each row using the ra, dec and distance as spherical polar coordinates, where distance is the distance from the observer along the line of sight. Rows are considered to match when their positions in this space are within error units of each other. The units of error are the same as those of distance.

As with sky matching, other longitude/latitude coordinate pairs may be used in place of right ascension and declination.

#### 7.1.5 exact: Exact Matching

matcher=exact values*='<matched-value>'
values*:
• matched-value: Value for exact match

The exact matcher compares arbitrary key values for exact equality. Rows are considered to match only if the values in their matched-value columns are exactly the same. These values can be strings, numbers, or anything else. A blank value never matches, not even with another blank one. Since the params parameter holds no values, it does not have to be specified. Note that the values must also be of the same type, so for instance a Long (64-bit) integer value will not match an Integer (32-bit) value.

#### 7.1.6 1d, 2d, ...: Isotropic Cartesian Matching

matcher=1d values*='<x>'
params='<error>'
tuning='<bin-factor>'
values*:
• x: Cartesian co-ordinate #1
params:
• error: Maximum Cartesian separation for match
tuning:
• bin-factor: Scaling factor to adjust bin size; larger values mean larger bins

matcher=2d values*='<x> <y>'
params='<error>'
tuning='<bin-factor>'
values*:
• x: Cartesian co-ordinate #1
• y: Cartesian co-ordinate #2
params:
• error: Maximum Cartesian separation for match
tuning:
• bin-factor: Scaling factor to adjust bin size; larger values mean larger bins

The 1d matcher compares positions in 1-dimensional Cartesian space. Rows are considered to match if their x column values differ by no more than error.

The 2d matcher compares postions in 2-dimensional Cartesian space. Rows are considered to match if the difference in their (x,y) positions reckoned using Pythagoras is less than error.

Matching in any number of Cartesian dimensions can be done by extending this syntax in the obvious way.

#### 7.1.7 2d_anisotropic, ...: Anisotropic Cartesian Matching

matcher=2d_anisotropic values*='<x> <y>'
params='<error-in-x> <error-in-y>'
tuning='<bin-factor>'
values*:
• x: Cartesian co-ordinate #1
• y: Cartesian co-ordinate #2
params:
• error-in-x: Axis length of error ellipse in Cartesian co-ordinate #1 direction
• error-in-y: Axis length of error ellipse in Cartesian co-ordinate #2 direction
tuning:
• bin-factor: Scaling factor to adjust bin size; larger values mean larger bins

The 2d_anisotropic matcher compares positions in 2-dimensional Cartesian space using an anisotropic metric. Rows are considered to match if their (x,y) positions fall within an error ellipse with axis lengths error-in-x, error-in-y of each other. This kind of match will typically be used for non-'spatial' spaces, for instance (magnitude,redshift) space, in which the metrics along different axes are not related to each other.

Matching in any number of dimensions of Cartesian space using an anisotropic metric can be done by extending this syntax in the obvious way.

#### 7.1.8 2d_cuboid, ...: Cuboid Cartesian Matching

matcher=2d_cuboid values*='<x> <y>'
params='<error-in-x> <error-in-y>'
tuning='<bin-factor>'
values*:
• x: Cartesian co-ordinate #1
• y: Cartesian co-ordinate #2
params:
• error-in-x: Half length of cuboid in Cartesian co-ordinate #1 direction
• error-in-y: Half length of cuboid in Cartesian co-ordinate #2 direction
tuning:
• bin-factor: Scaling factor to adjust bin size; larger values mean larger bins

The 2d_cuboid matcher compares positions in 2-dimensional Cartesian space in cuboidal cells. Rows are considered to match if their (x,y) positions fall within an error cuboid with half-axis lengths error-in-x, error-in-y of each other. This kind of match is suitable for grouping items into pixels, though it's not a very efficient way of doing that.

Matching in any number of dimensions using N-dimensional hyper-cuboids can be done by extending this syntax in the obvious way.

#### 7.1.9 1d_err, 2d_err, ...: Cartesian Matching with Per-Object Errors

matcher=2d_err values*='<x> <y> <error>'
params='<scale>'
tuning='<bin-factor>'
values*:
• x: Cartesian co-ordinate #1
• y: Cartesian co-ordinate #2
• error: Per-object error radius
params:
• scale: Rough average of per-object error distance; just used for tuning in conjunction with bin factor
tuning:
• bin-factor: Scaling factor to adjust bin size; larger values mean larger bins

The 1d_err, 2d_err, ... matchers compare positions in N-dimensional Cartesian space like the 1d, 2d matchers described in Section 7.1.6, except that the match radius can be different for each row. Rows are considered to match when the separation reckoned by Pythagoras between the x, y, ... positions is no larger than the sum of the two per-row error values. Matching in any number of Cartesian dimensions can be done by extending this syntax in the obvious way.

The scale parameter must be supplied, and should be approximately the characteristic size of the per-object error values. In conjunction with the bin-factor tuning parameter its value affects the performance of the match, but not the result.

#### 7.1.10 2d_ellipse: Cartesian Matching of Elliptical Regions

matcher=2d_ellipse values*='<x> <y> <primary-radius> <secondary-radius>
<orientation-angle/degrees>'
params='<scale>'
tuning='<bin-factor>'
values*:
• x: X coordinate of centre
• y: Y coordinate of centre
• primary-radius: Length of ellipse semi-major axis
• secondary-radius: Length of ellipse semi-minor axis
• orientation-angle/degrees: Angle from X axis towards Y axis of semi-major axis
params:
• scale: Rough average of per-object error distance; just used for tuning in conjunction with bin factor
tuning:
• bin-factor: Scaling factor to adjust bin size; larger values mean larger bins

The 2d_ellipse matcher compares elliptical regions in a 2d plane for overlap. Each row has to specify five values, giving the centre, the major and minor radii, and the orientation angle of an ellipse. Rows are considered to match if there is any overlap between the ellipses. The goodness of match is a normalised generalisation of the symmetrical case used by the isotropic matcher, in which the best possible match is two concentric ellipses, and the worst allowable match is when the circumferences just touch.

Note the orientation angle is measured anticlockwise from the horizontal, unlike the position angle used by the skyellipse matcher.

The scale parameter must be supplied, and should be approximately the characteristic size of the per-object major radius. In conjunction with the bin-factor tuning parameter its value affects the performance of the match, but not the result.

#### 7.1.11 Custom Matchers

For advanced users, it is possible to supply the name of a class on the classpath which implements the uk.ac.starlink.table.join.MatchEngine interface and which has a no-arg constructor. This allows java programmers to write their own matchers using any match criteria and binning algorithms they choose.

#### 7.1.12 Matcher Combinations

In addition to the matching criteria listed in the previous subsections, you can build your own by combining any of these. To do this, take the two (or more) matchers that you want to use, and separate their names with a "+" character. The values* parameters of the combined matcher should then hold the concatenation of the values* entries of the constituent matchers, and the same for the params parameter.

So for instance the matcher "sky+1d" could be used with the following syntax:

matcher=sky+1d values*='<ra/degrees> <dec/degrees> <x>'
params='<max-error/arcsec> <error>'
tuning='<healpix-k> <bin-factor>'
values*:
• ra/degrees: Right Ascension
• dec/degrees: Declination
• x: Cartesian co-ordinate #1
params:
• max-error/arcsec: Maximum separation along a great circle
• error: Maximum Cartesian separation for match
tuning:
• healpix-k: Controls sky pixel size. Legal range 0 - 29. 0 is 60deg, 20 is 0.2".
• bin-factor: Scaling factor to adjust bin size; larger values mean larger bins
This would compare positions on the sky with an additional scalar constraint. Rows are considered to match if both their ra, dec positions are within max-error arcseconds of each other along a great circle (as for matcher=sky) and their x values differ by no more than error (as for matcher=1d).

This example might be used for instance to identify objects from two catalogues which are within a couple of arcseconds and also 0.5 blue magnitudes of each other. Rolling your own matchers in this way can give you quite flexible match constraints.

When identifying the closest match (e.g. find=best1 in tmatch2) the "distance" measure is obtained by scaling the distances from each of the constituent matchers and adding these scaled distances in quadrature, so that each element of the matcher has approximately equal weight. Scaling is generally done using the maximum permissible match radius (or equivalent), so the distance measure looks something like d = sqrt([dA/max(dA)]2 + [dB/max(dB)]2). However the details are a bit dependent on which matchers you are combining.

Note that in STILTS v3.0-9 and earlier, a linear unscaled distance measure was used here instead, which did not give very meaningful Best match results.

### 7.2 Multi-Object Matches

The generic matching in STILTS is determined by specified match criteria, as described in Section 7.1. These criteria give conditions for whether two items (table rows) count as matched with each other. In the case of a pair match, as provided by tmatch2, it is clear how this is to be interpreted.

However, some of the matching tasks (tmatchn in group mode and tmatch1) search for match groups which may have more than two members. This section explains precisely how STILTS applies the pair-wise matching criteria it is given to identifying multi-object groups.

In a multi-object match context, the matcher identifies a matched group as the largest possible group of objects in which each is linked by a pair match to any other object in the group - it is a group of "friends of friends". Formally, the set of matched groups is a set of disjoint graphs whose nodes are input table rows and whose edges are successful pair matches, where no successful pair match exists between nodes in different elements of that set. Thus the set has a minimal number of elements, and each of its elements is a matched group of maximal size. The important point to note is that for any particular pair in a matched group, there is no guarantee that the two objects match each other, only that you can hop from one to the other via pairs which do match.

So in the case of a multi-object sky match on a field which is very crowded compared to the specified error radius, it is quite possible for all the objects in the input table(s) to end up as part of the same large matching group. Results at or near this percolation threshold are (a) probably not useful and (b) likely to take a long time to run. Some care should therefore be exercised when specifying match criteria in multi-object match contexts.

## 8 Plotting

As of version 3.0 (October 2014), STILTS offers plotting commands corresponding to the new-style plots in version 4 of the TOPCAT application. The commands are currently:

(In previous versions the less capable commands plot2d, plot3d and plothist were available - these are now deprecated, but described in Section 9).

These commands all have a similar structure. The plot surface, or geometry of the plot, is defined by which command you use (for instance, if you want to plot longitude/latitude data on the celestial sphere, use plot2sky). Content is added to the plot by specifying zero or more plot layers, as described in Section 8.3 below. Section 8.4 describes the shading modes which affect how colouring is performed for some of the layer types. Once a plot has been specified, it can be displayed on the screen or exported in some way according to a selected output mode (Section 8.5) and perhaps export format (Section 8.6). Plots displayed to the screen are by default "live" - they can be resized and navigated around (pan, zoom, rotate, ...) using the mouse in the same way as in a TOPCAT window.

These commands allow you to make all the plots that can be produced with TOPCAT, in some cases with more flexibility in configuration. Unlike TOPCAT, the size of table you can plot is not limited by the size of table you can load into the application. In most cases, STILTS will generate plots from arbitrarily large data sets with fixed (and modest) memory requirements. Performance is of course highly dependent on the details of the plot, but for instance an all-sky density plot for 2 billion points can be produced in the order of 30 minutes.

### 8.1 Plot Parameters

The plotting commands offer a great deal of control over what is plotted and how it is represented, and thus unavoidably have lots of parameters. When looking at the command documentation in Appendix B the Usage sections may look rather daunting. However, the discussion below and the Examples sections should help. Generating a simple plot is straightforward and can be done with only four or five parameters; if you want to represent more complicated data or have specific preferences for appearance then you can consult the documentation for the additional options.

As a simple example, if a file "cat.fits" contains the columns RMAG and BMAG for red and blue magnitudes, you can draw a two-dimensional colour-magnitude scatter plot with the command:

   stilts plot2plane layer_1=mark in_1=cat.fits x_1=BMAG-RMAG y_1=BMAG

Since an output file is not specified, the plot is shown in a window on the screen. This plot window is "live" - you can resize the window, or pan and zoom around it using the same mouse controls as in TOPCAT. To send the output to a PNG file, do instead:
   stilts plot2plane layer_1=mark in_1=cat.fits x_1=BMAG-RMAG y_1=BMAG out=fig.png


We can adjust the plot by inverting the Y axis so it increases downwards instead of upwards:

   stilts plot2plane
yflip=true
layer_1=mark in_1=cat.fits x_1=BMAG-RMAG y_1=BMAG

The parameters of the plot now fall into two groups. Global parameters, without suffixes, make global adjustments to the plot. In this example yflip=true inverts the Y axis. Layer parameters, with suffixes, are introduced by a layer parameter and grouped together by a given suffix. Each layer group defines a plot layer with content to be drawn on the plot surface. In this case the layer is of type mark (draw markers) and the suffix is "_1". Global and Layer parameters are described separately in the following subsections.

#### 8.1.1 Global Parameters

The global plot parameters are documented in the usage sections of the various plot commands (e.g. Appendix B.10.1). They deal with things like positioning the plot axes, fixing the data bounds, selecting font types and sizes, adjusting grids and tickmarks, configuring how interactive navigation works, managing data storage, and so on. They are all optional, since they all have sensible defaults, for instance data bounds will be determined from the supplied data if they are not given explicitly.

#### 8.1.2 Layer Parameters

The layer parameters come in groups, each specifying the details of one plot layer. Each layer type has its own list of parameters. A plot layer is introduced on the command line with a parameter of the form

   layer<suffix>=<layer-type>

and any other parameters with the same <suffix> are considered to apply to the same layer. In the basic example we considered:
   stilts plot2plane layer_1=mark in_1=cat.fits x_1=BMAG-RMAG y_1=BMAG

the suffix is "_1" and the layer type associated with it is mark (plotting markers to make a scatter plot). The different layer types are documented in Section 8.3, and each has its own set of parameters, some of which are mandatory and some which are optional with sensible defaults. In the documentation, the suffix is represented as "N". For instance the mark layer type requires you to specify an input table (inN) and point positions (xN and yN). Since the suffix we have used in the example for the layerN parameter is "_1", we have written in_1, x_1 and y_1. The mark layer has some optional style parameters as well, so we could adjust the plot's appearance by adding shape_1=cross size_1=4 color_1=blue.

You can have as many layers as you like (even none), so we could overplot two datasets from different input files like this:

   stilts plot2plane
layer_1=mark in_1=cat1.fits x_1=BMAG-RMAG   y_1=BMAG  color_1=magenta size_1=5
layer_2=mark in_2=cat2.fits x_2=mag_b-mag_r y_2=mag_b color_2=cyan    size_2=5

We have assigned different colours to the different layers and boosted the marker size to 5 pixels.

As a convenience, if the same value is used for all the layers, you can omit the suffix. So to avoid having to specify the same markers size for both layers, you can write instead:

   stilts plot2plane
size=5
layer_1=mark in_1=cat1.fits x_1=BMAG-RMAG   y_1=BMAG  color_1=magenta
layer_2=mark in_2=cat2.fits x_2=mag_b-mag_r y_2=mag_b color_2=teal

Although the size parameter no longer has an explicit suffix, it's still a layer parameter, it just applies to multiple layers. This shorthand works for all layer parameters. Here is another example which also shows how you can use the icmdN parameter to pre-process input data prior to performing the plot. Here, we make two different selections of the input rows to plot two different data sets.
   stilts plot2plane
in=cat.fits x=BMAG-RMAG y=BMAG
layer_1=mark icmd_1='select vel<1000'  color_1=blue
layer_2=mark icmd_2='select vel>=1000' color_2=red

The input tables and data values are the same for both datasets, so we can just supply the parameters in, x and y, rather than in_1, in_2 etc.

Any string can be used as a suffix, including the empty string (though an empty string can cause confusion if there are multiple layers). The suffixing is also slightly more sophisticated than described above; to find parameters relating to a layer with a given suffix, the parameter looks first using the whole suffix, and strips single characters off it until it has none left. So if a layer is introduced with the parameter layer_ab, you can give the marker shape using any of the parameters shape_ab, shape_a, shape_ or shape. If more than one of these is present, the first one in that list will be used (the order in which they appear on the command line is not significant). This can be used to group sets of layers.

By default, if multiple layers are specified, they are plotted in the order in which the introducing layerN parameters appear on the command line. This may be relevant, since layers plotted later sometimes obscure ones plotted earlier. You can alter the order of plotting with the seq (global) parameter, which is a comma-separated list of layer suffixes giving the sequence in which layers should be plotted. So adding "seq=_2,_1" would cause layer _2 to be plotted before layer _1, instead of the other way round.

By default, if more than one layer is plotted, a legend will appear labelling the datasets. The dataset labels appearing in the legend are by default the layer suffixes specified on the command line. However, the labels can be given explicitly with the legendN parameter, so for instance in the example above leglabel_1=Slow leglabel_2=Fast would adjust the legend accordingly. Legend appearance and positioning can be adjusted by various leg* global parameters.

#### 8.1.3 Animation

The plotting commands can be used to produce animations. This is done by supplying an animation control table using the animate parameter (which has associated afmt and acmd parameters for specifying its file format and applying filters). One output image is produced for each row of the control table. The columns of the table have names which correspond to plot command parameters, and for each row, the basic plot command is executed with the parameters on the command line supplied or replaced by those from the table. This is most commonly used for providing a movie of the kind of navigation you can do interactively with the mouse, but other applications are possible.

For instance, given the following animation control table with the name "bounds.txt", in ASCII format:

  #  xmax  ymax
4.0   2.0
3.0   1.5
2.0   1.0
1.0   0.5

then this command:
   stilts plot2plane xmin=0 ymin=0
layer_1=mark in_1=gums_smc.fits x_1=ag y_1=av
animate=bounds.txt afmt=ascii

would produce a 4-frame animation zooming in towards the origin.

If output is to the screen (omode=swing, the default) the animation can be seen directly. If it is to an output file (omode=out) then a number of output files is written with sequence numbers, so adding the parameter "out=x.png" to the above command would produce 4 files, x-1.png, x-2.png, x-3.png and x-4.png. Padding zeros are used to keep the files in alphanumeric sequence, so for instance in a 500-frame animation the first one would be named x-001.png. STILTS does not actually turn these files into a single animated output file, but you can use other tools to do this, for instance using ImageMagick:

   convert x-*.png xmovie.gif

or ffmpeg:
   ffmpeg -i 'x-%03d.png' -framerate 15 -pix_fmt yuv420p xmovie.webm


You can create the animation control table any way you like, but you may find the tloop command convenient. For instance the above table can be written like this:

   stilts tloop xmax 4 0 -1 ocmd='addcol ymax xmax*0.5' ofmt=ascii out=bounds.txt

Alternatively, you can generate a table like this inline using the loop scheme. A common requirement is to produce an animation of rotating a 3-d plot, here's an example of how to do that:
   stilts plot2sphere layer_1=mark in_1=hip_main.fits lon_1=radeg lat_1=dedeg r_1=plx \
animate=:loop:15,375,2 acmd='colmeta -name phi 1'  The phi parameter controls the angle from which the 3D plot is viewed, and here it is incremented by 2 degrees for each frame. The same thing would work for plot2cube as well as plot2sphere. Note that producing animations in this way is usually much more efficient than writing a shell script which invokes STILTS multiple times. The plot commands also employ multi-threading when animating to output files, so should make efficient use of multi-core machines (though currently animations to the screen are not multi-threaded). ### 8.2 Surface Types The different plot2* commands correspond to different plot surface geometries. The different commands come with their own specific axis configuration parameters. Some of the plot layer types are specific to certain surface types. When supplying data from input tables to plot layers, the coordinate values you need to supply (and hence the corresponding parameter names) are determined not by the layer type, but by the surface type. For instance, point positions for layer N on a 2-d Cartesian surface (plot2plane command) are given using parameters xN and yN, but when plotting to the celestial sphere (plot2sky command) you supply lonN and latN). The following list summarises the available surface types and their corresponding positional coordinates. Plane (plot2plane) 2-dimensional Cartesian axes. Positional coordinates are supplied as x, y pairs. Note that this command can also be used to draw histograms. Sky (plot2sky) Celestial sphere. Positional coordinates are supplied as lon, lat pairs, giving longitude and latitude in decimal degrees. A number of different projections are available, and conversion between different celestial coordinate systems can also be performed. You could use it for other spherical coordinate systems too (like the surface of a planet). Cube (plot2cube) 3-dimensional Cartesian axes. Positional coordinates are supplied as x, y, z triples. Sphere (plot2sphere) 3-dimensional isotropic space with spherical polar coordinates. Positional coordinates are supplied as lon, lat, r triples, giving longitude and latitude in decimal degrees, and radius in an arbitrary unit. The plotting surface (space) is similar to Cube, except that the unit distance is always the same in all three directions. Time (plot2time) 2-dimensional axes, but the horizontal axis represents time. The axis may be labelled in various ways (ISO-8601 dates, decimal year, MJD etc). Positional coordinates are supplied as t, y pairs. Time can be represented in input data in various ways; if sufficient metadata is provided in the input format the epoch can be determined automatically, otherwise it may be necessary to specify the time representation being used. ### 8.3 Layer Types The different plot layers and how to configure them with parameters is given in the following subsections. The layers which may be plotted on a particular surface depend on the plot geometry, so not all of these are available for every plot command. #### 8.3.1 mark Plots a marker of fixed size and shape at each position. Usage Overview:  layerN=mark shapeN=filled_circle|open_circle|... sizeN=<pixels> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> <pos-coord-paramsN> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2plane layer1=mark in1=rrlyrae.fits x1=p1 y1=peak_to_peak_g  icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] shapeN = filled_circle|open_circle|... (MarkerShape) Sets the shape of markers that are plotted at each position of the scatter plot. The available options are: • filled_circle • open_circle • cross • x • open_square • open_diamond • open_triangle_up • open_triangle_down • fat_circle • fat_cross • fat_x • fat_square • fat_diamond • fat_triangle_up • fat_triangle_up • filled_square • filled_diamond • filled_triangle_up • filled_triangle_down [Default: filled_circle] sizeN = <pixels> (Integer) Size of the scatter plot markers. The unit is pixels, in most cases the marker is approximately twice the size of the supplied value. [Default: 1] #### 8.3.2 size Plots a marker of fixed shape but variable size at each position. The size is determined by an additional input data value. The actual size of the markers depends on the setting of the autoscale parameter. If autoscaling is off, then the basic size of each marker is the input data value in units of pixels. If autoscaling is on, then the data values are gathered for all the currently visible points, and a scaling factor is applied so that the largest ones will be a sensible size (a few tens of pixels). This basic size can be further adjusted with the scale factor. Currently data values of zero always correspond to marker size of zero, negative data values are not represented, and the mapping is linear. An absolute maximum of 100 pixels is also imposed on marker sizes. Other options may be introduced in future. Note: for marker sizes that correspond to data values in data coordinates, you may find Error plotting more appropriate. Usage Overview:  layerN=size shapeN=filled_circle|open_circle|... scaleN=<factor> autoscaleN=true|false shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> <pos-coord-paramsN> sizeN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2sky projection=aitoff xpix=500 ypix=250 layer1=size in1=messier.xml shading1=transparent lon1=RA lat1=DEC size1=Radius  autoscaleN = true|false (Boolean) Determines whether the basic size of variable sized markers is automatically scaled to have a sensible size. If true, then the sizes of all the plotted markers are examined, and some dynamically calculated factor is applied to them all to make them a sensible size (by default, the largest ones will be a few tens of pixels). If false, the sizes will be the actual input values in units of pixels. If auto-scaling is off, then markers will keep exactly the same screen size during pan and zoom operations; if it's on, then the visible sizes will change according to what other points are currently plotted. Marker size is also affected by the scale parameter. [Default: true] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] scaleN = <factor> (Double) Scales the size of variable-sized markers. The default is 1, smaller or larger values multiply the visible sizes accordingly. [Default: 1] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] shapeN = filled_circle|open_circle|... (MarkerShape) Sets the shape of markers that are plotted at each position of the scatter plot. The available options are: • filled_circle • open_circle • cross • x • open_square • open_diamond • open_triangle_up • open_triangle_down • fat_circle • fat_cross • fat_x • fat_square • fat_diamond • fat_triangle_up • fat_triangle_up • filled_square • filled_diamond • filled_triangle_up • filled_triangle_down [Default: filled_circle] sizeN = <num-expr> (String) Size to draw each sized marker. Units are pixels unless auto-scaling is in effect, in which case units are arbitrary. The plotted size is also affected by the scale value. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.3 sizexy Plots a shaped marker with variable horizontal and vertical extents at each position. The X and Y dimensions are determined by two additional input data values. The actual size of the markers depends on the setting of the autoscale parameter. If autoscaling is off, the basic dimensions of each marker are given by the input data values in units of pixels. If autoscaling is on, the data values are gathered for all the currently visible points, and scaling factors are applied so that the largest ones will be a sensible size (a few tens of pixels). This autoscaling happens independently for the X and Y directions. The basic sizes can be further adjusted with the scale factor. Currently data values of zero always correspond to marker dimension of zero, negative data values are not represented, and the mapping is linear. An absolute maximum of 100 pixels is also imposed on marker sizes. Other options may be introduced in future. Note: for marker sizes that correspond to data values in data coordinates, you may find Error plotting more appropriate. Usage Overview:  layerN=sizexy shapeN=open_rectangle|open_triangle|... thickN=<int-value> scaleN=<factor> autoscaleN=true|false shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> <pos-coord-paramsN> xsizeN=<num-expr> ysizeN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2plane layer1=sizexy in1=dr5qso.fits shape1=filled_rectangle x1=psfmag_u-psfmag_g y1=psfmag_r-psfmag_z xsize1=exp(psfmag_g) ysize1=exp(psfmag_r) xmin=-3 xmax=1 ymin=1 ymax=3.2 autoscaleN = true|false (Boolean) Determines whether the basic size of variable sized markers is automatically scaled to have a sensible size. If true, then the sizes of all the plotted markers are examined, and some dynamically calculated factor is applied to them all to make them a sensible size (by default, the largest ones will be a few tens of pixels). If false, the sizes will be the actual input values in units of pixels. If auto-scaling is off, then markers will keep exactly the same screen size during pan and zoom operations; if it's on, then the visible sizes will change according to what other points are currently plotted. Marker size is also affected by the scale parameter. [Default: true] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] scaleN = <factor> (Double) Scales the size of variable-sized markers. The default is 1, smaller or larger values multiply the visible sizes accordingly. [Default: 1] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] shapeN = open_rectangle|open_triangle|... (BasicXYShape) The available options are: • open_rectangle • open_triangle • open_triangle_down • open_diamond • open_ellipse • filled_rectangle • filled_triangle • filled_triangle_down • filled_diamond • filled_ellipse [Default: open_rectangle] thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] xsizeN = <num-expr> (String) Horizontal extent of each marker. Units are pixels unless auto-scaling is in effect, in which case units are arbitrary. The value is a numeric algebraic expression based on column names as described in Section 10. ysizeN = <num-expr> (String) Vertical extent of each marker. Units are pixels unless auto-scaling is in effect, in which case units are arbitrary. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.4 xyvector Plots directed lines from the data position given delta values for the coordinates. The plotted markers are typically little arrows, but there are other options. In some cases the supplied data values give the actual extents in data coordinates for the plotted vectors but sometimes the data is on a different scale or in different units to the positional coordinates. As a convenience for this case, the plotter can optionally scale the magnitudes of all the vectors to make them a reasonable size on the plot, so by default the largest ones are a few tens of pixels long. This auto-scaling is turned off by default, but it can be activated with the autoscale option. Whether autoscaling is on or off, the scale option can be used to apply a fixed scaling factor. Usage Overview:  layerN=xyvector arrowN=small_arrow|medium_arrow|... thickN=<int-value> scaleN=<factor> autoscaleN=true|false shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> xN=<num-expr> yN=<num-expr> xdeltaN=<num-expr> ydeltaN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=xyvector in1=gavo_g2.fits x1=x y1=y xdelta1=velX ydelta1=velY autoscale1=true thick1=1 xmin=9 xmax=11 ymin=12 ymax=13.5 arrowN = small_arrow|medium_arrow|... (MultiPointShape) How arrows are represented. The available options are: • small_arrow • medium_arrow • large_arrow • small_open_dart • medium_open_dart • large_open_dart • small_filled_dart • medium_filled_dart • large_filled_dart • lines • capped_lines [Default: small_arrow] autoscaleN = true|false (Boolean) Determines whether the default size of variable-sized markers like vectors and ellipses are automatically scaled to have a sensible size. If true, then the sizes of all the plotted markers are examined, and some dynamically calculated factor is applied to them all to make them a sensible size (by default, the largest ones will be a few tens of pixels). If false, the sizes will be the actual input values interpreted in data coordinates. If auto-scaling is on, then markers will keep approximately the same screen size during zoom operations; if it's off, they will keep the same size in data coordinates. Marker size is also affected by the scale parameter. [Default: false] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] scaleN = <factor> (Double) Affects the size of variable-sized markers like vectors and ellipses. The default value is 1, smaller or larger values multiply the visible sizes accordingly. [Default: 1] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] xN = <num-expr> (String) Horizontal coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. xdeltaN = <num-expr> (String) Vector component in the X direction. The value is a numeric algebraic expression based on column names as described in Section 10. yN = <num-expr> (String) Vertical coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. ydeltaN = <num-expr> (String) Vector component in the Y direction. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.5 xyerror Plots symmetric or asymmetric error bars in some or all of the plot dimensions. The shape of the error "bars" is quite configurable, including (for 2-d and 3-d errors) ellipses, rectangles etc aligned with the axes. Usage Overview:  layerN=xyerror errorbarN=none|lines|capped_lines|... thickN=<int-value> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> xN=<num-expr> yN=<num-expr> xerrhiN=<num-expr> xerrloN=<num-expr> yerrhiN=<num-expr> yerrloN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane in=J_MNRAS_440_1571.vot x=S500 y=S160 layer1=mark size1=5 shape1=fat_circle layer2=xyerror xerrhi2=e_S500 yerrhi2=e_S160 errorbar2=capped_lines thick2=1 xlog=true ylog=true shading=flat xmin=0.012 xmax=1 ymin=0.01 ymax=10 errorbarN = none|lines|capped_lines|... (MultiPointShape) How errorbars are represented. The available options are: • none • lines • capped_lines • caps • arrows • ellipse • crosshair_ellipse • rectangle • crosshair_rectangle • filled_ellipse • filled_rectangle [Default: lines] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] xN = <num-expr> (String) Horizontal coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. xerrhiN = <num-expr> (String) Error in the X coordinate in the positive direction. If no corresponding negative error value is supplied, then this value is also used in the negative direction, i.e. in that case errors are assumed to be symmetric. The value is a numeric algebraic expression based on column names as described in Section 10. xerrloN = <num-expr> (String) Error in the X coordinate in the negative direction. If left blank, it is assumed to take the same value as the positive error. The value is a numeric algebraic expression based on column names as described in Section 10. yN = <num-expr> (String) Vertical coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. yerrhiN = <num-expr> (String) Error in the Y coordinate in the positive direction. If no corresponding negative error value is supplied, then this value is also used in the negative direction, i.e. in that case errors are assumed to be symmetric. The value is a numeric algebraic expression based on column names as described in Section 10. yerrloN = <num-expr> (String) Error in the Y coordinate in the negative direction. If left blank, it is assumed to take the same value as the positive error. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.6 xyellipse Plots an ellipse (or rectangle, triangle, or other similar figure) defined by two principal radii and an optional angle of rotation, the so-called position angle. This angle, if specified, is in degrees and gives the angle counterclockwise from the horizontal axis to the first principal radius. In some cases the supplied data values give the actual extents in data coordinates for the plotted ellipses but sometimes the data is on a different scale or in different units to the positional coordinates. As a convenience for this case, the plotter can optionally scale the magnitudes of all the ellipses to make them a reasonable size on the plot, so by default the largest ones are a few tens of pixels long. This auto-scaling is turned off by default, but it can be activated with the autoscale option. Whether autoscaling is on or off, the scale option can be used to apply a fixed scaling factor. Usage Overview:  layerN=xyellipse ellipseN=ellipse|crosshair_ellipse|... thickN=<int-value> scaleN=<factor> autoscaleN=true|false shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> xN=<num-expr> yN=<num-expr> raN=<num-expr> rbN=<num-expr> posangN=<deg-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane in=mgc_ok.fits x=mgc_alpha_j2000 y=mgc_delta_j2000 ra=bulge_re/3600. rb=bulge_re*bulge_e/3600. posang=bulge_pa autoscale=false scale=10 color=blue layer1=xyellipse ellipse1=filled_ellipse shading1=transparent opaque1=4 layer2=xyellipse ellipse2=crosshair_ellipse aspect=1 xmin=181.3 xmax=181.9 autoscaleN = true|false (Boolean) Determines whether the default size of variable-sized markers like vectors and ellipses are automatically scaled to have a sensible size. If true, then the sizes of all the plotted markers are examined, and some dynamically calculated factor is applied to them all to make them a sensible size (by default, the largest ones will be a few tens of pixels). If false, the sizes will be the actual input values interpreted in data coordinates. If auto-scaling is on, then markers will keep approximately the same screen size during zoom operations; if it's off, they will keep the same size in data coordinates. Marker size is also affected by the scale parameter. [Default: false] ellipseN = ellipse|crosshair_ellipse|... (MultiPointShape) How ellipses are represented. The available options are: • ellipse • crosshair_ellipse • filled_ellipse • rectangle • crosshair_rectangle • filled_rectangle • open_triangle • filled_triangle • lines • capped_lines • arrows [Default: ellipse] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] posangN = <deg-expr> (String) Orientation of the ellipse. The value is the angle in degrees from the X axis towards the Y axis of the first principal axis of the ellipse. The value is a numeric algebraic expression based on column names as described in Section 10. raN = <num-expr> (String) Ellipse first principal radius. The value is a numeric algebraic expression based on column names as described in Section 10. rbN = <num-expr> (String) Ellipse second principal radius. If this value is blank, the two radii will be assumed equal, i.e. the ellipses will be circles. The value is a numeric algebraic expression based on column names as described in Section 10. scaleN = <factor> (Double) Affects the size of variable-sized markers like vectors and ellipses. The default value is 1, smaller or larger values multiply the visible sizes accordingly. [Default: 1] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] xN = <num-expr> (String) Horizontal coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. yN = <num-expr> (String) Vertical coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.7 xycorr Plots an error ellipse (or rectangle or other similar figure) defined by errors in the X and Y directions, and a correlation between the two errors. The supplied correlation is a dimensionless value in the range -1..+1 and is equal to the covariance divided by the product of the X and Y errors. The covariance matrix is thus:  [ xerr*xerr xerr*yerr*xycorr ] [ xerr*yerr*xycorr yerr*yerr ]  In some cases the supplied data values give the actual extents in data coordinates for the plotted ellipses but sometimes the data is on a different scale or in different units to the positional coordinates. As a convenience for this case, the plotter can optionally scale the magnitudes of all the ellipses to make them a reasonable size on the plot, so by default the largest ones are a few tens of pixels long. This auto-scaling is turned off by default, but it can be activated with the autoscale option. Whether autoscaling is on or off, the scale option can be used to apply a fixed scaling factor. This plot type is suitable for use with the <x>_error and <x>_<y>_corr columns in the Gaia source catalogue. Usage Overview:  layerN=xycorr ellipseN=ellipse|crosshair_ellipse|... thickN=<int-value> scaleN=<factor> autoscaleN=true|false shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> xN=<num-expr> yN=<num-expr> xerrN=<num-expr> yerrN=<num-expr> xycorrN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane in=tgas_source.fits icmd='select skyDistanceDegrees(ra,dec,56.9,23.9)<0.4' x=pmra y=pmdec layer1=mark xerrhi2=pmra_error yerrhi2=pmdec_error color2=cyan shading2=transparent layer2a=xyerror errorbar2a=filled_rectangle opaque2a=10 layer2b=xyerror errorbar2b=crosshair_rectangle opaque2b=4 layer3=xycorr autoscale3=false xerr3=pmra_error yerr3=pmdec_error xycorr3=pmra_pmdec_corr ellipse3=crosshair_ellipse aspect=1 xmin=17 xmax=24 ymin=-48 ymax=-42 autoscaleN = true|false (Boolean) Determines whether the default size of variable-sized markers like vectors and ellipses are automatically scaled to have a sensible size. If true, then the sizes of all the plotted markers are examined, and some dynamically calculated factor is applied to them all to make them a sensible size (by default, the largest ones will be a few tens of pixels). If false, the sizes will be the actual input values interpreted in data coordinates. If auto-scaling is on, then markers will keep approximately the same screen size during zoom operations; if it's off, they will keep the same size in data coordinates. Marker size is also affected by the scale parameter. [Default: false] ellipseN = ellipse|crosshair_ellipse|... (MultiPointShape) How ellipses are represented. The available options are: • ellipse • crosshair_ellipse • filled_ellipse • rectangle • crosshair_rectangle • filled_rectangle • open_triangle • filled_triangle • lines • capped_lines • arrows [Default: ellipse] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] scaleN = <factor> (Double) Affects the size of variable-sized markers like vectors and ellipses. The default value is 1, smaller or larger values multiply the visible sizes accordingly. [Default: 1] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] xN = <num-expr> (String) Horizontal coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. xerrN = <num-expr> (String) Error in the X coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. xycorrN = <num-expr> (String) Correlation beteween the errors in the X and Y directions. This is a dimensionless quantity in the range -1..+1, and is equivalent to the covariance divided by the product of the X and Y error values themselves. It corresponds to the *_corr values supplied in the Gaia source catalogue. The value is a numeric algebraic expression based on column names as described in Section 10. yN = <num-expr> (String) Vertical coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. yerrN = <num-expr> (String) Error in the Y coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.8 link2 Plots a line linking two positions from the same input table row. Usage Overview:  layerN=link2 thickN=<int-value> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> <pos-coord-params1N> <pos-coord-params2N> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-params1N> , <pos-coord-params2N> give 2 positions for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be x1N, y1N, x2N and y2N. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2sky clon=14.78 clat=-72.1525 radius=0.0015 sex=false layer_h=mark in_h=ngc346.fits lon_h=_RAJ2000 lat_h=_DEJ2000 color_h=red layer_g=mark in_g=ngc346xGaiadr1.fits lon_g=ra lat_g=dec color_g=blue shading_g=flat size_g=3 in_x=ngc346xGaiadr1.fits lon1_x=_RAJ2000 lat1_x=_DEJ2000 lon2_x=ra lat2_x=dec shading_x=flat layer_xl=link2 color_xl=forestgreen layer_xm=mark2 color_xm=greenyellow size_xm=4 shape_xm=open_circle seq=_xm,_xl,_h,_g leglabel_h=HST leglabel_g='Gaia DR1' legseq=_h,_g legpos=0.95,0.95 icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing point-to-point links. Zero, the default value, means a 1-pixel-wide line is used, and larger values make drawn lines thicker. [Default: 0] #### 8.3.9 mark2 Plots 2 similar markers of fixed size and shape representing 2 separate positions from the same input table row. This is a convenience option that can be used with other plot layers based on 2 positions. Usage Overview:  layerN=mark2 shapeN=filled_circle|open_circle|... sizeN=<pixels> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> <pos-coord-params1N> <pos-coord-params2N> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-params1N> , <pos-coord-params2N> give 2 positions for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be x1N, y1N, x2N and y2N. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2sky clon=14.78 clat=-72.1525 radius=0.0015 sex=false layer_h=mark in_h=ngc346.fits lon_h=_RAJ2000 lat_h=_DEJ2000 color_h=red layer_g=mark in_g=ngc346xGaiadr1.fits lon_g=ra lat_g=dec color_g=blue shading_g=flat size_g=3 in_x=ngc346xGaiadr1.fits lon1_x=_RAJ2000 lat1_x=_DEJ2000 lon2_x=ra lat2_x=dec shading_x=flat layer_xl=link2 color_xl=greenyellow layer_xm=mark2 color_xm=forestgreen size_xm=4 shape_xm=open_circle seq=_xm,_xl,_h,_g leglabel_h=HST leglabel_g='Gaia DR1' legseq=_h,_g legpos=0.95,0.95 icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] shapeN = filled_circle|open_circle|... (MarkerShape) Sets the shape of markers that are plotted at each position of the scatter plot. The available options are: • filled_circle • open_circle • cross • x • open_square • open_diamond • open_triangle_up • open_triangle_down • fat_circle • fat_cross • fat_x • fat_square • fat_diamond • fat_triangle_up • fat_triangle_up • filled_square • filled_diamond • filled_triangle_up • filled_triangle_down [Default: filled_circle] sizeN = <pixels> (Integer) Size of the scatter plot markers. The unit is pixels, in most cases the marker is approximately twice the size of the supplied value. [Default: 1] #### 8.3.10 poly4 Draws a closed quadrilateral given the coordinates of its vertices supplied as 4 separate positions. The way that the polygon is drawn (outline, fill etc) is determined using the polymode option. Polygons smaller than a configurable threshold size in pixels are by default represented by a replacement marker, so the position of even a very small polygon is still visible on the screen. Usage Overview:  layerN=poly4 polymodeN=outline|border|fill|cross|star thickN=<int-value> minsizeN=<pixels> minshapeN=filled_circle|open_circle|... shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> <pos-coord-params1N> <pos-coord-params2N> <pos-coord-params3N> <pos-coord-params4N> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-params1N> , <pos-coord-params2N> , <pos-coord-params3N> , <pos-coord-params4N> give 4 positions for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be x1N, y1N, x2N, y2N, x3N, y3N, x4N and y4N. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2sky in=big_tab_VIR_VIS_CSA_public.fits icmd='every 32' lon1=LON_CORNER_1 lat1=LAT_CORNER_1 lon2=LON_CORNER_2 lat2=LAT_CORNER_2 lon3=LON_CORNER_3 lat3=LAT_CORNER_3 lon4=LON_CORNER_4 lat4=LAT_CORNER_4 aux=RADIUS layer_o=poly4 polymode_o=outline shading_o=aux layer_f=poly4 polymode_f=fill shading_f=aux opaque_f=4 auxmap=rainbow auxvisible=false xpix=300 ypix=300 labelpos=none icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] minshapeN = filled_circle|open_circle|... (MarkerShape) Defines the shape of markers plotted instead of the actual polygon shape, for polygons that are smaller than the size threshold defined by minsize. The available options are: • filled_circle • open_circle • cross • x • open_square • open_diamond • open_triangle_up • open_triangle_down • fat_circle • fat_cross • fat_x • fat_square • fat_diamond • fat_triangle_up • fat_triangle_up • filled_square • filled_diamond • filled_triangle_up • filled_triangle_down [Default: x] minsizeN = <pixels> (Integer) Defines a threshold size in pixels below which, instead of the polygon defined by the other parameters, a replacement marker will be painted instead. If this is set to zero, then only the shape itself will be plotted, but if it is small it may appear as only a single pixel. By setting a larger value, you can ensure that the position of even small polygons is easily visible, at the expense of giving them an artificial shape and size. This value also defines the size of the replacement markers. [Default: 1] polymodeN = outline|border|fill|cross|star (PolygonShape) Polygon drawing mode. Different options are available, including drawing an outline round the edge and filling the interior with colour. The available options are: • outline: draws a line round the outside of the polygon • border: draws a line butting up to the outside of the polygon; may look better for adjacent shapes, but more expensive to draw • fill: fills the interior of the polygon • cross: draws a line round the outside of the polygon and lines between all the vertices • star: draws a line round the outside of the polygon and lines from the nominal center to each vertex [Default: outline] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing polygons. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled polygons contain no line drawings. [Default: 0] #### 8.3.11 mark4 Plots 4 similar markers of fixed size and shape representing 4 separate positions from the same input table row. This is a convenience option that can be used with other plot layers based on 4 positions. Usage Overview:  layerN=mark4 shapeN=filled_circle|open_circle|... sizeN=<pixels> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> <pos-coord-params1N> <pos-coord-params2N> <pos-coord-params3N> <pos-coord-params4N> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-params1N> , <pos-coord-params2N> , <pos-coord-params3N> , <pos-coord-params4N> give 4 positions for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be x1N, y1N, x2N, y2N, x3N, y3N, x4N and y4N. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2plane in=big_tab_VIR_VIS_CSA_public.fits icmd='select IOF_055<0.005' icmd='select lon_center>250&&lon_center<300&&lat_center>-65&&lat_center<-16' x1=LON_CORNER_1 y1=LAT_CORNER_1 x2=LON_CORNER_2 y2=LAT_CORNER_2 x3=LON_CORNER_3 y3=LAT_CORNER_3 x4=LON_CORNER_4 y4=LAT_CORNER_4 layer_q=poly4 polymode_q=fill shading_q=transparent opaque_q=4 layer_m=mark4 color_m=404040 shape_m=open_circle size_m=3  icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] shapeN = filled_circle|open_circle|... (MarkerShape) Sets the shape of markers that are plotted at each position of the scatter plot. The available options are: • filled_circle • open_circle • cross • x • open_square • open_diamond • open_triangle_up • open_triangle_down • fat_circle • fat_cross • fat_x • fat_square • fat_diamond • fat_triangle_up • fat_triangle_up • filled_square • filled_diamond • filled_triangle_up • filled_triangle_down [Default: filled_circle] sizeN = <pixels> (Integer) Size of the scatter plot markers. The unit is pixels, in most cases the marker is approximately twice the size of the supplied value. [Default: 1] #### 8.3.12 polygon Draws a closed polygon given an array of coordinates that define its vertices. In fact this plot requires the position of the first vertex supplied as a positional value in the usual way (e.g. X and Y coordinates) and the second, third etc vertices supplied as an array using the otherpoints parameter. Invocation might therefore look like "xN=x1 yN=y1 otherpointsN=array(x2,y2, x3,y3, x4,y4)". Usage Overview:  layerN=polygon useposN=true|false polymodeN=outline|border|fill|cross|star thickN=<int-value> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> <pos-coord-paramsN> otherpointsN=<array-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2sky in=big_tab_VIR_VIS_CSA_public.fits icmd='select ALTITUDE>4e4&&ALTITUDE<4.3e4' layer=polygon polymode=fill lon=LON_CENTER lat=LAT_CENTER otherpoints=array(lon_corner_1,lat_corner_1,lon_corner_2,lat_corner_2) shading=weighted weight=IR_TEMPERATURE auxmap=plasma clon=83 clat=34 radius=11 icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] otherpointsN = <array-expr> (String) Array of coordinates giving the points of the vertices defining the polygon to be drawn. These coordinates are given as an interleaved array by this parameter, e.g. (x1,y1, x2,y2, y3,y3). The basic position for the row being plotted either is or is not included as the first vertex, according to the setting of the usepos parameter. Some expression language functions that can be useful when specifying this parameter are array() and parseDoubles(). The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here. polymodeN = outline|border|fill|cross|star (PolygonShape) Polygon drawing mode. Different options are available, including drawing an outline round the edge and filling the interior with colour. The available options are: • outline: draws a line round the outside of the polygon • border: draws a line butting up to the outside of the polygon; may look better for adjacent shapes, but more expensive to draw • fill: fills the interior of the polygon • cross: draws a line round the outside of the polygon and lines between all the vertices • star: draws a line round the outside of the polygon and lines from the nominal center to each vertex [Default: outline] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing polygons. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled polygons contain no line drawings. [Default: 0] useposN = true|false (Boolean) Determines whether the basic positional coordinates are included as one of the polygon vertices or not. The polygon has N+1 vertices if true, or N vertices if false, where N is the number of vertices supplied by the array coordinate. If false, the basic position is ignored for the purposes of drawing the polygon. [Default: true] #### 8.3.13 area Plots a region on the plotting surface specified by a string or array of numbers. The area may be specified as an STC-S string (as for example in an ObsCore or EPN-TAP s_region column) or using an array of numbers representing a polygon, circle or point as flagged using the DALI/VOTable extended type (xtype) marker, or as an ASCII-encoded MOC. Areas smaller than a configurable threshold size in pixels are by default represented by a replacement marker, so the position of even a very small area is still visible on the screen. This plot type is generally intended for displaying relatively small shapes such as instrument footprints. It can be used for areas that are larger as well, but there may be issues with use, for instance auto-determination of the initial plot region may not work so well, and the rendering of shapes that are large relative to the sky may be inaccurate. These issues may be addressed in future releases. Usage Overview:  layerN=area polymodeN=outline|border|fill|cross|star thickN=<int-value> minsizeN=<pixels> minshapeN=filled_circle|open_circle|... shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> areaN=<area-expr> areatypeN=STC-S|POLYGON|CIRCLE|POINT|MOC-ASCII|UNIQ|TFCAT inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2sky reflectlon=false sex=false clon=348.9 clat=79.8 radius=1.0 in=crism.fits icmd='select sensor_id==0x4c' area_p=s_region areatype_p=stc-s layer_pf=area polymode_pf=fill color_pf=1199ff shading_pf=transparent layer_pl=area polymode_pl=outline color_pl=grey  areaN = <area-expr> (String) Expression giving the geometry of a 2D region on the plot. It may be a string- or array-valued expression, and its interpretation depends on the value of the corresponding areatype parameter. The value is a Area value algebraic expression based on column names as described in Section 10. areatypeN = STC-S|POLYGON|CIRCLE|POINT|MOC-ASCII|UNIQ|TFCAT (AreaMapper) Selects the form in which the Area value for parameter areaN is supplied. Options are: • STC-S: Region description using STC-S syntax; see TAP 1.0, section 6. Note there are some restrictions: <frame>, <refpos> and <flavor> metadata are ignored, polygon winding direction is ignored (small polygons are assumed) and the INTERSECTION and NOT constructions are not supported. The non-standard MOC construction is supported. • POLYGON: 2n-element array (x1,y1, x2,y2,...); a NaN,NaN pair can be used to delimit distinct polygons. • CIRCLE: 3-element array (x,y,r) • POINT: 2-element array (x,y) • MOC-ASCII: Region description using ASCII MOC syntax; see MOC 1.1 2.3.2. Note there are currently a few issues with MOC plotting, especially for large pixels. • UNIQ: Region description representing a single HEALPix cell as defined by an UNIQ value, see MOC 1.1 sec 2.3.1. • TFCAT: Time-Frequency region defined by the TFCat standard. Support is currently incomplete; holes in Polygons and MultiPolygons are not displayed correctly, single Points may not be displayed, and Coordinate Reference System information is ignored. If left blank, a guess will be taken depending on the data type of the value supplied for the areaN value. icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] minshapeN = filled_circle|open_circle|... (MarkerShape) Defines the shape of markers plotted instead of the actual polygon shape, for polygons that are smaller than the size threshold defined by minsize. The available options are: • filled_circle • open_circle • cross • x • open_square • open_diamond • open_triangle_up • open_triangle_down • fat_circle • fat_cross • fat_x • fat_square • fat_diamond • fat_triangle_up • fat_triangle_up • filled_square • filled_diamond • filled_triangle_up • filled_triangle_down [Default: x] minsizeN = <pixels> (Integer) Defines a threshold size in pixels below which, instead of the polygon defined by the other parameters, a replacement marker will be painted instead. If this is set to zero, then only the shape itself will be plotted, but if it is small it may appear as only a single pixel. By setting a larger value, you can ensure that the position of even small polygons is easily visible, at the expense of giving them an artificial shape and size. This value also defines the size of the replacement markers. [Default: 1] polymodeN = outline|border|fill|cross|star (PolygonShape) Polygon drawing mode. Different options are available, including drawing an outline round the edge and filling the interior with colour. The available options are: • outline: draws a line round the outside of the polygon • border: draws a line butting up to the outside of the polygon; may look better for adjacent shapes, but more expensive to draw • fill: fills the interior of the polygon • cross: draws a line round the outside of the polygon and lines between all the vertices • star: draws a line round the outside of the polygon and lines from the nominal center to each vertex [Default: outline] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing polygons. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled polygons contain no line drawings. [Default: 0] #### 8.3.14 central Plots the nominal central point of an area. This appears just like a normal marker plot, but can be used when the available geometry information is an area description (such as an STC-S string or an array of polygon vertices) rather than coordinate values such as an X,Y pair. The position plotted is the nominal center of the shape as determined by the plotting code; that may or may not correspond to the actual center. Usage Overview:  layerN=central shapeN=filled_circle|open_circle|... sizeN=<pixels> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> areaN=<area-expr> areatypeN=STC-S|POLYGON|CIRCLE|POINT|MOC-ASCII|UNIQ|TFCAT inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane xmin=136.7 xmax=138.5 ymin=-5.7 ymax=-4.2 in=crism.fits icmd='select sensor_id==0x53' area=s_region areatype=STC-S layer1=area polymode1=fill shading1=density densemap1=heat layer2=central shape2=fat_circle size2=3 color2=black  areaN = <area-expr> (String) Expression giving the geometry of a 2D region on the plot. It may be a string- or array-valued expression, and its interpretation depends on the value of the corresponding areatype parameter. The value is a Area value algebraic expression based on column names as described in Section 10. areatypeN = STC-S|POLYGON|CIRCLE|POINT|MOC-ASCII|UNIQ|TFCAT (AreaMapper) Selects the form in which the Area value for parameter areaN is supplied. Options are: • STC-S: Region description using STC-S syntax; see TAP 1.0, section 6. Note there are some restrictions: <frame>, <refpos> and <flavor> metadata are ignored, polygon winding direction is ignored (small polygons are assumed) and the INTERSECTION and NOT constructions are not supported. The non-standard MOC construction is supported. • POLYGON: 2n-element array (x1,y1, x2,y2,...); a NaN,NaN pair can be used to delimit distinct polygons. • CIRCLE: 3-element array (x,y,r) • POINT: 2-element array (x,y) • MOC-ASCII: Region description using ASCII MOC syntax; see MOC 1.1 2.3.2. Note there are currently a few issues with MOC plotting, especially for large pixels. • UNIQ: Region description representing a single HEALPix cell as defined by an UNIQ value, see MOC 1.1 sec 2.3.1. • TFCAT: Time-Frequency region defined by the TFCat standard. Support is currently incomplete; holes in Polygons and MultiPolygons are not displayed correctly, single Points may not be displayed, and Coordinate Reference System information is ignored. If left blank, a guess will be taken depending on the data type of the value supplied for the areaN value. icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] shapeN = filled_circle|open_circle|... (MarkerShape) Sets the shape of markers that are plotted at each position of the scatter plot. The available options are: • filled_circle • open_circle • cross • x • open_square • open_diamond • open_triangle_up • open_triangle_down • fat_circle • fat_cross • fat_x • fat_square • fat_diamond • fat_triangle_up • fat_triangle_up • filled_square • filled_diamond • filled_triangle_up • filled_triangle_down [Default: filled_circle] sizeN = <pixels> (Integer) Size of the scatter plot markers. The unit is pixels, in most cases the marker is approximately twice the size of the supplied value. [Default: 1] #### 8.3.15 lines Plots an N-segment line for each input row, with the X and Y coordinate arrays each supplied by an N-element array value. Usage Overview:  layerN=lines thickN=<pixels> dashN=dot|dash|...|<a,b,...> antialiasN=true|false shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> xsN=<array-expr> ysN=<array-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane in1=LRS_NPW_V010_20071101.cdf layer1=lines xs=multiply(paramfrequency,1e-6) xlabel=f/MHz ys=RX1 thick=2
icmd='every 100' xmin=13 xmax=16 xpix=660 auxvisible=false

antialiasN = true|false       (Boolean)
If true, plotted lines are drawn with antialising. Antialised lines look smoother, but may take perceptibly longer to draw. Only has any effect for bitmapped output formats.

[Default: false]

dashN = dot|dash|...|<a,b,...>       (float[])
Determines the dash pattern of the line drawn. If null (the default), the line is solid.

Possible values for dashed lines are dot, dash, longdash, dotdash. You can alternatively supply a comma-separated list of on/off length values such as "4,2,8,2".

icmdN = <cmds>       (ProcessingStep[])
Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table.

Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored.

ifmtN = <in-format>       (String)
Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables.

[Default: (auto)]

inN = <table>       (StarTable)
The location of the input table. This may take one of the following forms:
• A filename.
• A URL.
• The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way.
• A scheme specification of the form :<scheme-name>:<scheme-args>.
• A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems.
In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently.
istreamN = true|false       (Boolean)
If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables.

[Default: false]

shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN>       (ShapeMode)
Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are:
• auto
• flat
• translucent
• transparent
• density
• aux
• weighted
Each of these options comes with its own set of parameters to specify the details of how colouring is done.

[Default: auto]

thickN = <pixels>       (Integer)
Thickness of plotted line in pixels.

[Default: 1]

xsN = <array-expr>       (String)
Array giving the X coordinate array for each line. In most cases, if a blank value is supplied but Y values are present then a suitable linear sequence, of the same length as the Y array, is assumed.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

ysN = <array-expr>       (String)
Array giving the Y coordinate array for each line. In most cases, if a blank value is supplied but X values are present then a suitable linear sequence, of the same length as the X array, is assumed.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

#### 8.3.16 marks

Plots N markers for each input row, with the X and Y coordinate values each supplied by an N-element array value.

Usage Overview:

   layerN=marks shapeN=filled_circle|open_circle|... sizeN=<pixels>
xsN=<array-expr> ysN=<array-expr> inN=<table> ifmtN=<in-format>
istreamN=true|false icmdN=<cmds>


All the parameters listed here affect only the relevant layer, identified by the suffix N.

Example:

shading=aux auxmap=sron aux=$index icmd='head 8' auxvisible=false legend=false layer0=lines opaque0=2 layer1=handles placement1=index fraction1=0.85  fractionN = <0..1> (Double) Provides a numeric value in the range 0..1 that may influence where the handle is placed. Currently, this is only relevant for placement=index, where it indicates how far through the array the reference (X,Y) position should be taken (0.0 means the first element, 1.0 means the last). For other values of placement it is ignored. [Default: 0.5] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] placementN = index|ymax|ymin|xmax|xmin|xymean (XYArrayPlacement) Determines where the handle will be positioned in relation to the X/Y array values. The available options are: • index: (X,Y) point at a certain fraction of the way through the arrays, as given by the fraction value; fraction=0.0 is the first element, fraction=1.0 is the last. • ymax: (X,Y) position at which the maximum Y value is located (fraction is ignored) • ymin: (X,Y) position at which the minimum Y value is located (fraction is ignored) • xmax: (X,Y) position at which the maximum X value is located (fraction is ignored) • xmin: (X,Y) position at which the minimum X value is located (fraction is ignored) • xymean: center of gravity of all the (X,Y) points (fraction is ignored) [Default: index] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] shapeN = filled_circle|open_circle|... (MarkerShape) Sets the shape of the marker that is drawn to identify the handle position. The available options are: • filled_circle • open_circle • cross • x • open_square • open_diamond • open_triangle_up • open_triangle_down • fat_circle • fat_cross • fat_x • fat_square • fat_diamond • fat_triangle_up • fat_triangle_up • filled_square • filled_diamond • filled_triangle_up • filled_triangle_down [Default: fat_square] sizeN = <pixels> (Integer) Sets the size of the marker that is drawn to identify the handle position. The unit is pixels, in most cases the marker is approximately twice the size of the supplied value. [Default: 4] xsN = <array-expr> (String) Array giving the X coordinate array for each line. In most cases, if a blank value is supplied but Y values are present then a suitable linear sequence, of the same length as the Y array, is assumed. The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here. ysN = <array-expr> (String) Array giving the Y coordinate array for each line. In most cases, if a blank value is supplied but X values are present then a suitable linear sequence, of the same length as the X array, is assumed. The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here. #### 8.3.18 yerrors Plots N error bars in the Y direction for each input row, with the X, Y and error bar extents each supplied by N-element array values. Usage Overview:  layerN=yerrors errorbarN=none|lines|capped_lines|caps|arrows thickN=<int-value> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> xsN=<array-expr> ysN=<array-expr> yerrhisN=<array-expr> yerrlosN=<array-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane in=LRS_NPW_V010_20071101.cdf shading=aux aux=epoch xs=divide(2.998e8,param$Frequency) ys=multiply(add(RX1,RX2),0.5)
layer_l=lines thick_l=2
layer_e=yerrors yerrhis_e=arrayFunc("abs(x)",subtract(RX1,RX2)) errorbar_e=capped_lines
auxmap=paired auxvisible=false
xmin=116 xmax=161 ymin=-184 ymax=-148 xpix=660 ypix=300 icmd='every 1000'
xlabel=lambda ylabel=Intensity

errorbarN = none|lines|capped_lines|caps|arrows       (MultiPointShape)
How errorbars are represented.

The available options are:

• none
• lines
• capped_lines
• caps
• arrows

[Default: lines]

icmdN = <cmds>       (ProcessingStep[])
Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table.

Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored.

ifmtN = <in-format>       (String)
Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables.

[Default: (auto)]

inN = <table>       (StarTable)
The location of the input table. This may take one of the following forms:
• A filename.
• A URL.
• The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way.
• A scheme specification of the form :<scheme-name>:<scheme-args>.
• A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems.
In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently.
istreamN = true|false       (Boolean)
If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables.

[Default: false]

shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN>       (ShapeMode)
Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are:
• auto
• flat
• translucent
• transparent
• density
• aux
• weighted
Each of these options comes with its own set of parameters to specify the details of how colouring is done.

[Default: auto]

thickN = <int-value>       (Integer)
Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings.

[Default: 0]

xsN = <array-expr>       (String)
Array giving the X coordinate array for each line. In most cases, if a blank value is supplied but Y values are present then a suitable linear sequence, of the same length as the Y array, is assumed.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

yerrhisN = <array-expr>       (String)
Array of errors in the Y coordinates in the positive direction. If no corresponding negative value is supplied, then this value is also used in the negative direction, i.e. in that case errors are assumed to be symmetric. Error exents must be positive; negative array elements are ignored.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

yerrlosN = <array-expr>       (String)
Array of errors in the Y coordinates in the negative direction. If left blank, it is assumed to take the same value as in the positive direction. Error extents must be positive; negative array elements are ignored.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

ysN = <array-expr>       (String)
Array giving the Y coordinate array for each line. In most cases, if a blank value is supplied but X values are present then a suitable linear sequence, of the same length as the X array, is assumed.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

#### 8.3.19 xyerrors

Plots N error bars in the X and Y directions for each input row, with the X, Y and error bar extents each supplied by N-element array values.

Usage Overview:

   layerN=xyerrors errorbarN=none|lines|capped_lines|... thickN=<int-value>
xsN=<array-expr> ysN=<array-expr> xerrhisN=<array-expr>
xerrlosN=<array-expr> yerrhisN=<array-expr>
yerrlosN=<array-expr> inN=<table> ifmtN=<in-format>
istreamN=true|false icmdN=<cmds>


All the parameters listed here affect only the relevant layer, identified by the suffix N.

Example:

   stilts plot2plane in=LRS_NPW_V010_20071101.cdf ys=RX1
layer_l=lines opaque_l=1
layer_xy=xyerrors opaque_xy=3.3 errorbar_xy=crosshair_ellipse
xerrhis_xy=constant(512,0.5) yerrhis_xy=arrayFunc("abs(x)",subtract(RX1,RX2))
xmin=125 xmax=144 ymin=-184 ymax=-145 xpix=660 icmd='every 1000'
auxmap=viridis auxvisible=false

errorbarN = none|lines|capped_lines|...       (MultiPointShape)
How errorbars are represented.

The available options are:

• none
• lines
• capped_lines
• caps
• arrows
• ellipse
• crosshair_ellipse
• rectangle
• crosshair_rectangle
• filled_ellipse
• filled_rectangle

[Default: lines]

icmdN = <cmds>       (ProcessingStep[])
Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table.

Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored.

ifmtN = <in-format>       (String)
Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables.

[Default: (auto)]

inN = <table>       (StarTable)
The location of the input table. This may take one of the following forms:
• A filename.
• A URL.
• The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way.
• A scheme specification of the form :<scheme-name>:<scheme-args>.
• A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems.
In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently.
istreamN = true|false       (Boolean)
If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables.

[Default: false]

shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN>       (ShapeMode)
Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are:
• auto
• flat
• translucent
• transparent
• density
• aux
• weighted
Each of these options comes with its own set of parameters to specify the details of how colouring is done.

[Default: auto]

thickN = <int-value>       (Integer)
Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings.

[Default: 0]

xerrhisN = <array-expr>       (String)
Array of errors in the X coordinates in the positive direction. If no corresponding negative value is supplied, then this value is also used in the negative direction, i.e. in that case errors are assumed to be symmetric. Error exents must be positive; negative array elements are ignored.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

xerrlosN = <array-expr>       (String)
Array of errors in the X coordinates in the negative direction. If left blank, it is assumed to take the same value as in the positive direction. Error extents must be positive; negative array elements are ignored.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

xsN = <array-expr>       (String)
Array giving the X coordinate array for each line. In most cases, if a blank value is supplied but Y values are present then a suitable linear sequence, of the same length as the Y array, is assumed.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

yerrhisN = <array-expr>       (String)
Array of errors in the Y coordinates in the positive direction. If no corresponding negative value is supplied, then this value is also used in the negative direction, i.e. in that case errors are assumed to be symmetric. Error exents must be positive; negative array elements are ignored.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

yerrlosN = <array-expr>       (String)
Array of errors in the Y coordinates in the negative direction. If left blank, it is assumed to take the same value as in the positive direction. Error extents must be positive; negative array elements are ignored.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

ysN = <array-expr>       (String)
Array giving the Y coordinate array for each line. In most cases, if a blank value is supplied but X values are present then a suitable linear sequence, of the same length as the X array, is assumed.

The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here.

#### 8.3.20 statline

Plots a single line based on a combination (typically the mean) of input array-valued coordinates. The input X and Y coordinates must be fixed-length arrays of length N; a line with N points is plotted, each point representing the mean (or median, minimum, maximum, ...) of all the input array elements at the corresponding position.

Note that because the X and Y arrays must be of a fixed size for all rows, and because combination is performed in both X and Y directions, this is typically only suitable for plotting combined spectra if they all share a common horizontal axis, e.g. are all sampled into the same wavelength bins. To visually combine spectra with non-uniform sampling, the arrayquantile plotter may be more useful.

Usage Overview:

   layerN=statline xcombineN=mean|median|min|max|q.01|...
ycombineN=mean|median|min|max|q.01|...
colorN=<rrggbb>|red|blue|... thickN=<pixels>
antialiasN=true|false xsN=<array-expr> ysN=<array-expr>
inN=<table> ifmtN=<in-format> istreamN=true|false
icmdN=<cmds>


All the parameters listed here affect only the relevant layer, identified by the suffix N.

Example:

   stilts plot2plane in=LRS_NPW_V010_20071101.cdf xs=multiply(paramfrequency,1e-6) ys=RX2 xlabel=f/MHz ylabel=RX2/dB xmin=0.7 xmax=2.0 icmd='select rx2[71]<-170' xpix=700 layer1=lines color1=cyan layer2=statline color2=red thick2=3  antialiasN = true|false (Boolean) If true, plotted lines are drawn with antialising. Antialised lines look smoother, but may take perceptibly longer to draw. Only has any effect for bitmapped output formats. [Default: false] colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 3] xcombineN = mean|median|min|max|q.01|... (Combiner) Defines how corresponding array elements on the X axis are combined together to produce the plotted value. The available options are: • mean: the mean of the combined values • median: the median • min: the minimum of all the combined values • max: the maximum of all the combined values • q.01: 1st percentile • q1: first quartile • q3: third quartile • q.99: 99th percentile • stdev: the sample standard deviation of the combined values • sum: the sum of all the combined values per bin • count: the number of non-blank values per bin (weight is ignored) [Default: mean] xsN = <array-expr> (String) Array giving the X coordinate array for each line. In most cases, if a blank value is supplied but Y values are present then a suitable linear sequence, of the same length as the Y array, is assumed. The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here. ycombineN = mean|median|min|max|q.01|... (Combiner) Defines how corresponding array elements on the Y axis are combined together to produce the plotted value. The available options are: • mean: the mean of the combined values • median: the median • min: the minimum of all the combined values • max: the maximum of all the combined values • q.01: 1st percentile • q1: first quartile • q3: third quartile • q.99: 99th percentile • stdev: the sample standard deviation of the combined values • sum: the sum of all the combined values per bin • count: the number of non-blank values per bin (weight is ignored) [Default: mean] ysN = <array-expr> (String) Array giving the Y coordinate array for each line. In most cases, if a blank value is supplied but X values are present then a suitable linear sequence, of the same length as the X array, is assumed. The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here. #### 8.3.21 statmark Plots a set of markers based on a combination (typically the mean) of input array-valued coordinates. The input X and Y coordinates must be fixed-length arrays of length N; N markers are plotted, each one representing the mean (or median, minimum, maximum, ...) of all the input array elements at the corresponding position. Note that because the X and Y arrays must be of a fixed size for all rows, and because combination is performed in both X and Y directions, this is typically only suitable for plotting combined spectra if they all share a common horizontal axis, e.g. are all sampled into the same wavelength bins. To visually combine spectra with non-uniform sampling, the arrayquantile plotter may be more useful. Usage Overview:  layerN=statmark xcombineN=mean|median|min|max|q.01|... ycombineN=mean|median|min|max|q.01|... colorN=<rrggbb>|red|blue|... shapeN=filled_circle|open_circle|... sizeN=<pixels> xsN=<array-expr> ysN=<array-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane in=LRS_NPW_V010_20071101.cdf ys=RX1 xmin=115 xmax=145 ymin=-183 ymax=-149 xpix=700 xcrowd=0.8 layer-d=lines color-d=wheat layer-m=statline ycombine-m=median color-m=LimeGreen thick-m=3 color-q=DodgerBlue size-q=4 layer-q1=statmark ycombine-q1=Q1 shape-q1=filled_triangle_up layer-q3=statmark ycombine-q3=Q3 shape-q3=filled_triangle_down leglabel-m=Median leglabel-q1='First Quartile' leglabel-q3='Third Quartile' legseq=-q3,-m,-q1 legpos=0.98,0.93 colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] shapeN = filled_circle|open_circle|... (MarkerShape) Sets the shape of markers that are plotted at each position of the scatter plot. The available options are: • filled_circle • open_circle • cross • x • open_square • open_diamond • open_triangle_up • open_triangle_down • fat_circle • fat_cross • fat_x • fat_square • fat_diamond • fat_triangle_up • fat_triangle_up • filled_square • filled_diamond • filled_triangle_up • filled_triangle_down [Default: filled_circle] sizeN = <pixels> (Integer) Size of the markers. The unit is pixels, in most cases the marker is approximately twice the size of the supplied value. [Default: 4] xcombineN = mean|median|min|max|q.01|... (Combiner) Defines how corresponding array elements on the X axis are combined together to produce the plotted value. The available options are: • mean: the mean of the combined values • median: the median • min: the minimum of all the combined values • max: the maximum of all the combined values • q.01: 1st percentile • q1: first quartile • q3: third quartile • q.99: 99th percentile • stdev: the sample standard deviation of the combined values • sum: the sum of all the combined values per bin • count: the number of non-blank values per bin (weight is ignored) [Default: mean] xsN = <array-expr> (String) Array giving the X coordinate array for each line. In most cases, if a blank value is supplied but Y values are present then a suitable linear sequence, of the same length as the Y array, is assumed. The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here. ycombineN = mean|median|min|max|q.01|... (Combiner) Defines how corresponding array elements on the Y axis are combined together to produce the plotted value. The available options are: • mean: the mean of the combined values • median: the median • min: the minimum of all the combined values • max: the maximum of all the combined values • q.01: 1st percentile • q1: first quartile • q3: third quartile • q.99: 99th percentile • stdev: the sample standard deviation of the combined values • sum: the sum of all the combined values per bin • count: the number of non-blank values per bin (weight is ignored) [Default: mean] ysN = <array-expr> (String) Array giving the Y coordinate array for each line. In most cases, if a blank value is supplied but X values are present then a suitable linear sequence, of the same length as the X array, is assumed. The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here. #### 8.3.22 arrayquantile Displays a quantile or quantile range for a set of plotted X/Y array pairs. If a table contains one spectrum per row in array-valued wavelength and flux columns, this plotter can be used to display a median of all the spectra, or a range between two quantiles. Smoothing options are available to even out noise arising from the pixel binning. For each row, the xs and ys arrays must be the same length as each other, but this plot type does not require all the arrays to be sampled into the same bins. The algorithm calculates quantiles for all the X,Y points plotted in each column of pixels. This means that more densely sampled spectra have more influence on the output than sparser ones. Note: in the current implementation, depending on the details of the configuration and the data, there may be some distortions or missing graphics near the edges of the plot. This may be improved in future releases, depending on feedback. Usage Overview:  layerN=arrayquantile colorN=<rrggbb>|red|blue|... transparencyN=0..1 quantilesN=<low-frac>[,<high-frac>] thickN=<pixels> smoothN=+<width>|-<count> kernelN=square|linear|epanechnikov|cos|cos2|gauss3|gauss6 joinN=none|polygon|lines horizontalN=true|false xsN=<array-expr> ysN=<array-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane in=xq100sub.fits xs=subWave ys=multiply(subFlux,1./mean(subFlux)) xlabel=Wavelength/nm ylabel='Normalised Flux' layer1=lines shading1=density densemap1=greyscale denseclip1=0.2,1 densefunc1=linear leglabel1=Spectra layer_q13=ArrayQuantile color_q13=DodgerBlue transparency_q13=0.5 quantiles_q13=0.25,0.75 leglabel_q13='Quartile Range' layer_med=ArrayQuantile color_med=blue join_med=lines leglabel_med=Median legend=true legpos=0.95,0.95 xpix=600 ypix=350 xmin=1348 xmax=1358 ymin=-0.2 ymax=2.2 colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] horizontalN = true|false (Boolean) Determines whether the trace bins are horizontal or vertical. If true, y quantiles are calculated for each pixel column, and if false, x quantiles are calculated for each pixel row. [Default: true] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] joinN = none|polygon|lines (QJoin) Defines the graphical style for connecting distinct quantile values. If smoothed samples are packed more closely than the pixel grid the option chosen here doesn't make much difference, but if there are gaps in the data along the sampled axis, it's useful to have a guide to the eye to join one quantile determination to the next. The available options are: • none: displayed quantile ranges are not joined • polygon: the area between a line connecting the upper quantiles and a line connecting the lower quantiles is filled • lines: a line of thickness given by thick is drawn from the center of each quantile range to the next [Default: polygon] kernelN = square|linear|epanechnikov|cos|cos2|gauss3|gauss6 (Kernel1dShape) The functional form of the smoothing kernel. The functions listed refer to the unscaled shape; all kernels are normalised to give a total area of unity. The available options are: • square: Uniform value: f(x)=1, |x|=0..1 • linear: Triangle: f(x)=1-|x|, |x|=0..1 • epanechnikov: Parabola: f(x)=1-x*x, |x|=0..1 • cos: Cosine: f(x)=cos(x*pi/2), |x|=0..1 • cos2: Cosine squared: f(x)=cos^2(x*pi/2), |x|=0..1 • gauss3: Gaussian truncated at 3.0 sigma: f(x)=exp(-x*x/2), |x|=0..3 • gauss6: Gaussian truncated at 6.0 sigma: f(x)=exp(-x*x/2), |x|=0..6 [Default: epanechnikov] quantilesN = <low-frac>[,<high-frac>] (Subrange) Defines the quantile or quantile range of values that should be marked in each pixel column (or row). The value may be a single number in the range 0..1 indicating the quantile which should be marked. Alternatively, it may be a pair of numbers, each in the range 0..1, separated by commas (<lo>,<hi>) indicating two quantile lines bounding an area to be filled. A pair of equal values "a,a" is equivalent to the single value "a". The default is 0.5, which means to mark the median value in each column, and could equivalently be specified 0.5,0.5. [Default: 0.5] smoothN = +<width>|-<count> (BinSizer) Configures the smoothing width. This is the characteristic width of the kernel function to be convolved with the density in one dimension to smooth the quantile function. If the supplied value is a positive number it is interpreted as a fixed width in the data coordinates of the X axis (if the X axis is logarithmic, the value is a fixed factor). If it is a negative number, then it will be interpreted as the approximate number of smooothing widths that fit in the width of the visible plot (i.e. plot width / smoothing width). If the value is zero, no smoothing is applied. When setting this value graphically, you can use either the slider to adjust the bin count or the numeric entry field to fix the bin width. [Default: 0] thickN = <pixels> (Integer) Sets the minimum extent of the markers that are plotted in each pixel column (or row) to indicate the designated value range. If the range is zero sized (quantiles specifies a single value rather than a pair) this will give the actual thickness of the plotted line. If the range is non-zero however, the line may be thicker than this in places according to the quantile positions. [Default: 3] transparencyN = 0..1 (Double) Transparency with which components are plotted, in the range 0 (opaque) to 1 (invisible). The value is 1-alpha. [Default: 0] xsN = <array-expr> (String) Array giving the X coordinate array for each line. In most cases, if a blank value is supplied but Y values are present then a suitable linear sequence, of the same length as the Y array, is assumed. The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here. ysN = <array-expr> (String) Array giving the Y coordinate array for each line. In most cases, if a blank value is supplied but X values are present then a suitable linear sequence, of the same length as the X array, is assumed. The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here. #### 8.3.23 line Plots a point-to-point line joining up the positions of data points. There are additional options to pre-sort the points according to their order on the X or Y axis (using the sortaxis value), and to vary the colour of the line along its length (using the aux value). The options for controlling the Aux colour map are controlled at the level of the plot itself, rather than by per-layer configuration. Usage Overview:  layerN=line colorN=<rrggbb>|red|blue|... thickN=<pixels> dashN=dot|dash|...|<a,b,...> sortaxisN=[X|Y] antialiasN=true|false auxnullcolorN=<rrggbb>|red|blue|... <pos-coord-paramsN> auxN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2time in=ACE_data.vot t=epoch layer1=line y1=Br zone1=A layer2=line y2=Bt zone2=B layer3=line y3=Bn zone3=C antialiasN = true|false (Boolean) If true, plotted lines are drawn with antialising. Antialised lines look smoother, but may take perceptibly longer to draw. Only has any effect for bitmapped output formats. [Default: false] auxN = <num-expr> (String) If supplied, this controls the colouring of the line along its length according to the value of this coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. auxnullcolorN = <rrggbb>|red|blue|... (Color) The color of points with a null value of the Aux coordinate, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. If the value is null, then points with a null Aux value will not be plotted at all. [Default: grey] colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] dashN = dot|dash|...|<a,b,...> (float[]) Determines the dash pattern of the line drawn. If null (the default), the line is solid. Possible values for dashed lines are dot, dash, longdash, dotdash. You can alternatively supply a comma-separated list of on/off length values such as "4,2,8,2". icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] sortaxisN = [X|Y] (AxisOpt) May be set to "X" or "Y" to ensure that the points are plotted in ascending order of the corresponding coordinate. This will ensure that the plotted line resembles a function of the corresponding coordinate rather than a scribble. The default (null) value causes the points to be joined in the sequence in which they appear in the table. If the points already appear in the table sorted according to the corresponding coordinate, this option has no visible effect, though it may slow things down. [Default: None] thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 1] #### 8.3.24 linearfit Plots a line of best fit for the data points. Usage Overview:  layerN=linearfit colorN=<rrggbb>|red|blue|... thickN=<pixels> dashN=dot|dash|...|<a,b,...> antialiasN=true|false <pos-coord-paramsN> weightN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2plane in=6dfgs_mini.xml x=RMAG y=BMAG layer1=mark layer2=linearfit  antialiasN = true|false (Boolean) If true, plotted lines are drawn with antialising. Antialised lines look smoother, but may take perceptibly longer to draw. Only has any effect for bitmapped output formats. [Default: false] colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] dashN = dot|dash|...|<a,b,...> (float[]) Determines the dash pattern of the line drawn. If null (the default), the line is solid. Possible values for dashed lines are dot, dash, longdash, dotdash. You can alternatively supply a comma-separated list of on/off length values such as "4,2,8,2". icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 1] weightN = <num-expr> (String) The weight associated with each data point for fitting purposes. This is used for calculating the coefficients of the line of best fit, and the correlation coefficient. If no coordinate is supplied, all points are assumed to have equal weight (1). Otherwise, any point with a null weight value is assigned a weight of zero, i.e. ignored. Given certain assumptions about independence of samples, a suitable value for the weight may be 1/(err*err), if err is the measurement error for each Y value. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.25 label Draws a text label at each position. You can select the font, where the labels appear in relation to the point positions, and how crowded the points have to get before they are suppressed. Usage Overview:  layerN=label texttypeN=plain|antialias|latex fontsizeN=<int-value> fontstyleN=standard|serif|mono fontweightN=plain|bold|italic|bold_italic anchorN=west|east|north|south|center colorN=<rrggbb>|red|blue|... xoffN=<pixels> yoffN=<pixels> spacingN=<pixels> crowdlimitN=<n> <pos-coord-paramsN> labelN=<txt-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2sky in=messier.xml lon=RA lat=DEC layer1=mark size1=3 layer2=label label2=NAME color2=black  anchorN = west|east|north|south|center (Anchor) Determines where the text appears in relation to the plotted points. Values are points of the compass. The available options are: • west • east • north • south • center [Default: west] colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] crowdlimitN = <n> (Integer) Sets the maximum number of labels in a label group. This many labels can appear closely spaced without being affected by the label spacing parameter. It is useful for instance if you are looking at pairs of points, which will always be close together; if you set this value to 2, an isolated pair of labels can be seen, but if it's 1 then they will only be plotted when they are distant from each other, which may only happen at very high magnifications. [Default: 2] fontsizeN = <int-value> (Integer) Size of the text font in points. [Default: 12] fontstyleN = standard|serif|mono (FontType) Font style for text. The available options are: • standard • serif • mono [Default: standard] fontweightN = plain|bold|italic|bold_italic (FontWeight) Font weight for text. The available options are: • plain • bold • italic • bold_italic [Default: plain] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] labelN = <txt-expr> (String) Column or expression giving the text of the label to be written near the position being labelled. Label values may be of any type (string or numeric) The value is a string algebraic expression based on column names as described in Section 10. spacingN = <pixels> (Integer) Determines the closest that labels can be spaced. If a group of labels is closer to another group than the value of this parameter, they will not be drawn, to avoid the display becoming too cluttered. The effect is that you can see individual labels when you zoom in, but not when there are many labelled points plotted close together on the screen. Set the value higher for less cluttered labelling. [Default: 12] texttypeN = plain|antialias|latex (TextSyntax) Determines how to turn label text into characters on the plot. Plain and Antialias both take the text at face value, but Antialias smooths the characters. LaTeX interprets the text as LaTeX source code and typesets it accordingly. When not using LaTeX, antialiased text usually looks nicer, but can be perceptibly slower to plot. At time of writing, on MacOS antialiased text seems to be required to stop the writing coming out upside-down for non-horizontal text (MacOS java bug). [Default: plain] xoffN = <pixels> (Integer) Allows fine adjustment of label positioning in the X direction. The value is a positive or negative pixel offset applied to the position of each plotted label. [Default: 0] yoffN = <pixels> (Integer) Allows fine adjustment of label positioning in the Y direction. The value is a positive or negative pixel offset applied to the position of each plotted label. [Default: 0] #### 8.3.26 arealabel Draws a text label near the center of each area.You can select the font, where the labels appear in relation to the point positions, and how crowded the points have to get before they are suppressed. This is just like a normal Label plot, but the positions are taken from an Area coordinate rather than normal positional coordinates. Usage Overview:  layerN=arealabel texttypeN=plain|antialias|latex fontsizeN=<int-value> fontstyleN=standard|serif|mono fontweightN=plain|bold|italic|bold_italic anchorN=west|east|north|south|center colorN=<rrggbb>|red|blue|... xoffN=<pixels> yoffN=<pixels> spacingN=<pixels> crowdlimitN=<n> areaN=<area-expr> areatypeN=STC-S|POLYGON|CIRCLE|POINT|MOC-ASCII|UNIQ|TFCAT labelN=<txt-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2sky reflectlon=false sex=false clon=18 clat=0 radius=36 xpix=550 ypix=600 in=countries.vot area=shape areatype=STC-S layer_1=area polymode_1=fill shading_1=aux aux_1=index opaque_1=2 layer_2=area polymode_2=outline shading_2=flat color_2=grey auxmap=paired auxvisible=false layer_3=arealabel label_3=name anchor_3=center color_3=black  anchorN = west|east|north|south|center (Anchor) Determines where the text appears in relation to the plotted points. Values are points of the compass. The available options are: • west • east • north • south • center [Default: west] areaN = <area-expr> (String) Expression giving the geometry of a 2D region on the plot. It may be a string- or array-valued expression, and its interpretation depends on the value of the corresponding areatype parameter. The value is a Area value algebraic expression based on column names as described in Section 10. areatypeN = STC-S|POLYGON|CIRCLE|POINT|MOC-ASCII|UNIQ|TFCAT (AreaMapper) Selects the form in which the Area value for parameter areaN is supplied. Options are: • STC-S: Region description using STC-S syntax; see TAP 1.0, section 6. Note there are some restrictions: <frame>, <refpos> and <flavor> metadata are ignored, polygon winding direction is ignored (small polygons are assumed) and the INTERSECTION and NOT constructions are not supported. The non-standard MOC construction is supported. • POLYGON: 2n-element array (x1,y1, x2,y2,...); a NaN,NaN pair can be used to delimit distinct polygons. • CIRCLE: 3-element array (x,y,r) • POINT: 2-element array (x,y) • MOC-ASCII: Region description using ASCII MOC syntax; see MOC 1.1 2.3.2. Note there are currently a few issues with MOC plotting, especially for large pixels. • UNIQ: Region description representing a single HEALPix cell as defined by an UNIQ value, see MOC 1.1 sec 2.3.1. • TFCAT: Time-Frequency region defined by the TFCat standard. Support is currently incomplete; holes in Polygons and MultiPolygons are not displayed correctly, single Points may not be displayed, and Coordinate Reference System information is ignored. If left blank, a guess will be taken depending on the data type of the value supplied for the areaN value. colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] crowdlimitN = <n> (Integer) Sets the maximum number of labels in a label group. This many labels can appear closely spaced without being affected by the label spacing parameter. It is useful for instance if you are looking at pairs of points, which will always be close together; if you set this value to 2, an isolated pair of labels can be seen, but if it's 1 then they will only be plotted when they are distant from each other, which may only happen at very high magnifications. [Default: 2] fontsizeN = <int-value> (Integer) Size of the text font in points. [Default: 12] fontstyleN = standard|serif|mono (FontType) Font style for text. The available options are: • standard • serif • mono [Default: standard] fontweightN = plain|bold|italic|bold_italic (FontWeight) Font weight for text. The available options are: • plain • bold • italic • bold_italic [Default: plain] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] labelN = <txt-expr> (String) Column or expression giving the text of the label to be written near the position being labelled. Label values may be of any type (string or numeric) The value is a string algebraic expression based on column names as described in Section 10. spacingN = <pixels> (Integer) Determines the closest that labels can be spaced. If a group of labels is closer to another group than the value of this parameter, they will not be drawn, to avoid the display becoming too cluttered. The effect is that you can see individual labels when you zoom in, but not when there are many labelled points plotted close together on the screen. Set the value higher for less cluttered labelling. [Default: 12] texttypeN = plain|antialias|latex (TextSyntax) Determines how to turn label text into characters on the plot. Plain and Antialias both take the text at face value, but Antialias smooths the characters. LaTeX interprets the text as LaTeX source code and typesets it accordingly. When not using LaTeX, antialiased text usually looks nicer, but can be perceptibly slower to plot. At time of writing, on MacOS antialiased text seems to be required to stop the writing coming out upside-down for non-horizontal text (MacOS java bug). [Default: plain] xoffN = <pixels> (Integer) Allows fine adjustment of label positioning in the X direction. The value is a positive or negative pixel offset applied to the position of each plotted label. [Default: 0] yoffN = <pixels> (Integer) Allows fine adjustment of label positioning in the Y direction. The value is a positive or negative pixel offset applied to the position of each plotted label. [Default: 0] #### 8.3.27 contour Plots position density contours. This provides another way (alongside the auto, density and weighted shading modes) to visualise the characteristics of overdense regions in a crowded plot. It's not very useful if you just have a few points. A weighting may optionally be applied to the quantity being contoured. To do this, provide a non-blank value for the weight coordinate, and use the combine parameter to define how the weights are combined (sum, mean, etc). The contours are currently drawn as pixels rather than lines so they don't look very beautiful in exported vector output formats (PDF, PostScript). This may be improved in the future. Usage Overview:  layerN=contour colorN=<rrggbb>|red|blue|... combineN=sum|mean|median|stdev|min|max|count nlevelN=<int-value> smoothN=<pixels> thickN=<pixels> scalingN=linear|log|equal zeroN=<number> <pos-coord-paramsN> weightN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2plane in=tgas_source.fits x=phot_g_mean_mag y=phot_g_mean_flux_error ylog=true xmax=14 ymin=10 layer1=mark shading1=density densemap1=greyscale layer2=contour scaling2=log nlevel=6  colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] combineN = sum|mean|median|stdev|min|max|count (Combiner) Defines the way that the weight values are combined when generating the value grid for which the contours will be plotted. If a weighting is supplied, the most useful values are mean which traces the mean values of a quantity and sum which traces the weighted sum. Other values such as median are of dubious validity because of the way that the smoothing is done. This value is ignored if the weighting coordinate weight is not set. The available options are: • sum: the sum of all the combined values per bin • mean: the mean of the combined values • median: the median • stdev: the sample standard deviation of the combined values • min: the minimum of all the combined values • max: the maximum of all the combined values • count: the number of non-blank values per bin (weight is ignored) [Default: sum] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] nlevelN = <int-value> (Integer) Number of countour lines drawn. In fact, this is an upper limit; if there is not enough variation in the plot's density, then fewer contour lines will be drawn. [Default: 5] scalingN = linear|log|equal (LevelMode) How the smoothed density is treated before contour levels are determined. The available options are: • linear: levels are equally spaced • log: level logarithms are equally spaced • equal: levels are spaced to provide equal-area inter-contour regions [Default: linear] smoothN = <pixels> (Integer) The linear size of the smoothing kernel applied to the density before performing the contour determination. If set too low the contours will be too crinkly, and if too high they will lose definition. Smoothing currently uses an approximately Gaussian kernel for extensive combination modes (count, sum) or a circular top hat for intensive modes (weighted mean). [Default: 5] thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 1] weightN = <num-expr> (String) Weighting of data points. If supplied, each point contributes a value to the histogram equal to the data value multiplied by this coordinate. If not supplied, the effect is the same as supplying a fixed value of one. The value is a numeric algebraic expression based on column names as described in Section 10. zeroN = <number> (Double) Determines the level at which the first contour (and hence all the others, which are separated from it by a fixed amount) are drawn. [Default: 1] #### 8.3.28 grid Plots 2-d data aggregated into rectangular cells. You can optionally use a weighting for the points, and you can configure how the values are combined to produce the output pixel values (colours). You can use this plotter in various ways, including as a 2-d histogram or weighted density map, or to plot gridded data. The X and Y dimensions of the grid cells (or equivalently histogram bins) can be configured either in terms of the data coordinates or relative to the plot dimensions. The way that data values are mapped to colours is usually controlled by options at the level of the plot itself, rather than by per-layer configuration. Usage Overview:  layerN=grid xbinsizeN=+<extent>|-<count> ybinsizeN=+<extent>|-<count> combineN=sum|sum-per-unit|count|... transparencyN=0..1 xphaseN=<number> yphaseN=<number> <pos-coord-paramsN> weightN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2plane layer1=grid in1=gk_hess.fits x1=g_min_ks y1=g_mag_abs weight1=n combine1=sum xbinsize1=0.2 ybinsize1=0.2 xphase1=0.5 yphase1=0.5 yflip=true auxfunc=log auxmap=viridis combineN = sum|sum-per-unit|count|... (Combiner) Defines how values contributing to the same grid cell are combined together to produce the value assigned to that cell, and hence its colour. The combined values are the weights, but if the weight coordinate is left blank, a weighting of unity is assumed. The available options are: • sum: the sum of all the combined values per bin • sum-per-unit: the sum of all the combined values per unit of bin size • count: the number of non-blank values per bin (weight is ignored) • count-per-unit: the number of non-blank values per unit of bin size (weight is ignored) • mean: the mean of the combined values • median: the median • q1: first quartile • q3: third quartile • min: the minimum of all the combined values • max: the maximum of all the combined values • stdev: the sample standard deviation of the combined values • hit: 1 if any values present, NaN otherwise (weight is ignored) [Default: mean] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] transparencyN = 0..1 (Double) Transparency with which components are plotted, in the range 0 (opaque) to 1 (invisible). The value is 1-alpha. [Default: 0] weightN = <num-expr> (String) Weighting of data points. If supplied, each point contributes a value to the histogram equal to the data value multiplied by this coordinate. If not supplied, the effect is the same as supplying a fixed value of one. The value is a numeric algebraic expression based on column names as described in Section 10. xbinsizeN = +<extent>|-<count> (BinSizer) Configures the extent of the density grid bins on the X axis. If the supplied value is a positive number it is interpreted as a fixed size in data coordinates (if the X axis is logarithmic, the value is a fixed factor). If it is a negative number, then it will be interpreted as the approximate number of bins to display across the plot in the X direction (though an attempt is made to use only round numbers for bin sizes). When setting this value graphically, you can use either the slider to adjust the bin count or the numeric entry field to fix the bin size. [Default: -30] xphaseN = <number> (Double) Controls where the zero point on the X axis is set. For instance if your bin size is 1, this value controls whether bin boundaries are at 0, 1, 2, .. or 0.5, 1.5, 2.5, ... etc. A value of 0 (or any integer) will result in a bin boundary at X=0 (linear X axis) or X=1 (logarithmic X axis). A fractional value will give a bin boundary at that value multiplied by the bin width. [Default: 0] ybinsizeN = +<extent>|-<count> (BinSizer) Configures the extent of the density grid bins on the Y axis. If the supplied value is a positive number it is interpreted as a fixed size in data coordinates (if the Y axis is logarithmic, the value is a fixed factor). If it is a negative number, then it will be interpreted as the approximate number of bins to display across the plot in the Y direction (though an attempt is made to use only round numbers for bin sizes). When setting this value graphically, you can use either the slider to adjust the bin count or the numeric entry field to fix the bin size. [Default: -30] yphaseN = <number> (Double) Controls where the zero point on the Y axis is set. For instance if your bin size is 1, this value controls whether bin boundaries are at 0, 1, 2, .. or 0.5, 1.5, 2.5, ... etc. A value of 0 (or any integer) will result in a bin boundary at X=0 (linear X axis) or X=1 (logarithmic X axis). A fractional value will give a bin boundary at that value multiplied by the bin width. [Default: 0] #### 8.3.29 fill If a two-dimensional dataset represents a single-valued function, this plotter will fill the area underneath the function's curve with a solid colour. Parts of the surface which would only be partially covered (because of rapid function variation within the width of a single pixel) are represented using appropriate alpha-blending. The filled area may alternatively be that above the curve or to its left or right. One example of its use is to reconstruct the appearance of a histogram plot from a set of histogram bins. For X,Y data which is not single-valued, the result may not be very useful. Usage Overview:  layerN=fill colorN=<rrggbb>|red|blue|... transparencyN=0..1 horizontalN=true|false positiveN=true|false <pos-coord-paramsN> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2time layer1=fill in1=iers.fits t1=decYear y1=lodErr ylog=true texttype=latex fontsize=16 colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] horizontalN = true|false (Boolean) Determines whether the filling is vertical (suitable for functions of the horizontal variable), or horizontal (suitable for functions of the vertical variable). If false, the fill is vertical (to the X axis), and if true, the fill is horizontal (to the Y axis). [Default: false] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] positiveN = true|false (Boolean) Determines the directional sense of the filling. If false, the fill is between the data points and negative infinity along the relevant axis (e.g. down from the data points to the bottom of the plot). If true, the fill is in the other direction. [Default: false] transparencyN = 0..1 (Double) Transparency with which components are plotted, in the range 0 (opaque) to 1 (invisible). The value is 1-alpha. [Default: 0] #### 8.3.30 quantile Plots a line through a given quantile of the values binned within each pixel column (or row) of a plot. The line is optionally smoothed using a configurable kernel and width, to even out noise arising from the pixel binning. Instead of a simple line through a given quantile, it is also possible to fill the region between two quantiles. One way to use this is to draw a line estimating a function y=f(x) (or x=g(y)) sampled by a noisy set of data points in two dimensions. Note: in the current implementation, depending on the details of the configuration and the data, there may be some distortions or missing graphics near the edges of the plot. This may be improved in future releases, depending on feedback. Usage Overview:  layerN=quantile colorN=<rrggbb>|red|blue|... transparencyN=0..1 quantilesN=<low-frac>[,<high-frac>] thickN=<pixels> smoothN=+<width>|-<count> kernelN=square|linear|epanechnikov|cos|cos2|gauss3|gauss6 joinN=none|polygon|lines horizontalN=true|false <pos-coord-paramsN> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2plane in=tgas_source.fits x=phot_g_mean_mag y=phot_g_mean_flux_error ylog=true xmax=15 ymin=10 layer.d=mark color.d=99ff99 layer.q4=quantile quantiles.q4=0.25,0.75 color.q4=magenta transparency.q4=0.35 layer.q2=quantile quantiles.q2=0.5 color.q2=SkyBlue thick.q2=4 smooth.q=0.05 leglabel.q4=Quartiles leglabel.q2=Median legseq=.q4,.q2 legpos=0.95,0.95 colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] horizontalN = true|false (Boolean) Determines whether the trace bins are horizontal or vertical. If true, y quantiles are calculated for each pixel column, and if false, x quantiles are calculated for each pixel row. [Default: true] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] joinN = none|polygon|lines (QJoin) Defines the graphical style for connecting distinct quantile values. If smoothed samples are packed more closely than the pixel grid the option chosen here doesn't make much difference, but if there are gaps in the data along the sampled axis, it's useful to have a guide to the eye to join one quantile determination to the next. The available options are: • none: displayed quantile ranges are not joined • polygon: the area between a line connecting the upper quantiles and a line connecting the lower quantiles is filled • lines: a line of thickness given by thick is drawn from the center of each quantile range to the next [Default: none] kernelN = square|linear|epanechnikov|cos|cos2|gauss3|gauss6 (Kernel1dShape) The functional form of the smoothing kernel. The functions listed refer to the unscaled shape; all kernels are normalised to give a total area of unity. The available options are: • square: Uniform value: f(x)=1, |x|=0..1 • linear: Triangle: f(x)=1-|x|, |x|=0..1 • epanechnikov: Parabola: f(x)=1-x*x, |x|=0..1 • cos: Cosine: f(x)=cos(x*pi/2), |x|=0..1 • cos2: Cosine squared: f(x)=cos^2(x*pi/2), |x|=0..1 • gauss3: Gaussian truncated at 3.0 sigma: f(x)=exp(-x*x/2), |x|=0..3 • gauss6: Gaussian truncated at 6.0 sigma: f(x)=exp(-x*x/2), |x|=0..6 [Default: epanechnikov] quantilesN = <low-frac>[,<high-frac>] (Subrange) Defines the quantile or quantile range of values that should be marked in each pixel column (or row). The value may be a single number in the range 0..1 indicating the quantile which should be marked. Alternatively, it may be a pair of numbers, each in the range 0..1, separated by commas (<lo>,<hi>) indicating two quantile lines bounding an area to be filled. A pair of equal values "a,a" is equivalent to the single value "a". The default is 0.5, which means to mark the median value in each column, and could equivalently be specified 0.5,0.5. [Default: 0.5] smoothN = +<width>|-<count> (BinSizer) Configures the smoothing width. This is the characteristic width of the kernel function to be convolved with the density in one dimension to smooth the quantile function. If the supplied value is a positive number it is interpreted as a fixed width in the data coordinates of the X axis (if the X axis is logarithmic, the value is a fixed factor). If it is a negative number, then it will be interpreted as the approximate number of smooothing widths that fit in the width of the visible plot (i.e. plot width / smoothing width). If the value is zero, no smoothing is applied. When setting this value graphically, you can use either the slider to adjust the bin count or the numeric entry field to fix the bin width. [Default: 0] thickN = <pixels> (Integer) Sets the minimum extent of the markers that are plotted in each pixel column (or row) to indicate the designated value range. If the range is zero sized (quantiles specifies a single value rather than a pair) this will give the actual thickness of the plotted line. If the range is non-zero however, the line may be thicker than this in places according to the quantile positions. [Default: 3] transparencyN = 0..1 (Double) Transparency with which components are plotted, in the range 0 (opaque) to 1 (invisible). The value is 1-alpha. [Default: 0] #### 8.3.31 histogram Plots a histogram. Bin heights may optionally be weighted by the values of some additional coordinate, supplied using the weight parameter. In this case you can choose how these weights are combined in each bin using the combine parameter. Various options are provided for configuring how the bar heights are calculated, but note that not all combinations of the available parameters will necessarily lead to meaningful visualisations. Usage Overview:  layerN=histogram colorN=<rrggbb>|red|blue|... transparencyN=0..1 binsizeN=+<width>|-<count> phaseN=<number> combineN=sum|sum-per-unit|count|... cumulativeN=none|forward|reverse normaliseN=none|area|unit|maximum|height barformN=open|filled|semi_filled|steps|semi_steps|spikes thickN=<pixels> dashN=dot|dash|...|<a,b,...> xN=<num-expr> weightN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=histogram in1=rrlyrae.fits x1=p1  barformN = open|filled|semi_filled|steps|semi_steps|spikes (Form) How histogram bars are represented. Note that options using transparent colours may not render very faithfully to some vector formats like PDF and EPS. The available options are: • open • filled • semi_filled • steps • semi_steps • spikes [Default: semi_filled] binsizeN = +<width>|-<count> (BinSizer) Configures the width of histogram bins. If the supplied string is a positive number, it is interpreted as a fixed width in the data coordinates of the X axis (if the X axis is logarithmic, the value is a fixed factor). If it is a negative number, then it will be interpreted as the approximate number of bins to display across the width of the plot (though an attempt is made to use only round numbers for bin widths). When setting this value graphically, you can use either the slider to adjust the bin count or the numeric entry field to fix the bin width. [Default: -30] colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] combineN = sum|sum-per-unit|count|... (Combiner) Defines how values contributing to the same bin are combined together to produce the value assigned to that bin, and hence its height. The combined values are those given by the weight coordinate, but if no weight is supplied, a weighting of unity is assumed. The available options are: • sum: the sum of all the combined values per bin • sum-per-unit: the sum of all the combined values per unit of bin size • count: the number of non-blank values per bin (weight is ignored) • count-per-unit: the number of non-blank values per unit of bin size (weight is ignored) • mean: the mean of the combined values • median: the median • q1: first quartile • q3: third quartile • min: the minimum of all the combined values • max: the maximum of all the combined values • stdev: the sample standard deviation of the combined values • hit: 1 if any values present, NaN otherwise (weight is ignored) [Default: sum] cumulativeN = none|forward|reverse (Cumulation) If set to forward/reverse the histogram bars plotted are calculated cumulatively; each bin includes the counts from all previous bins working up/down the independent axis. Note that setting cumulative plotting may not make much sense with some other parameter values, for instance averaging aggregation modes. For reasons of backward compatibility, the values true and false may be used as aliases for forward and none. The available options are: • none: The value plotted for each bin uses the samples accumulated in that bin. • forward: The value plotted for each bin uses the samples accumulated all the way from negative infinity to that bin. • reverse: The value plotted for each bin uses the samples accumulated all the way from positive infinity to that bin. [Default: none] dashN = dot|dash|...|<a,b,...> (float[]) Determines the dash pattern of the line drawn. If null (the default), the line is solid. Possible values for dashed lines are dot, dash, longdash, dotdash. You can alternatively supply a comma-separated list of on/off length values such as "4,2,8,2". icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] normaliseN = none|area|unit|maximum|height (Normalisation) Defines how, if at all, the bars of histogram-like plots are normalised or otherwise scaled vertically. Note that some of the normalisation options may not make much sense with some other parameter values, for instance averaging aggregation modes. The available options are: • none: No normalisation is performed. • area: The total area of histogram bars is normalised to unity. For cumulative plots, this behaves like height. • unit: Histogram bars are scaled by the inverse of the bin width in data units. For cumulative plots, this behaves like none. • maximum: The height of the tallest histogram bar is normalised to unity. For cumulative plots, this behaves like height. • height: The total height of histogram bars is normalised to unity. [Default: none] phaseN = <number> (Double) Controls where the horizontal zero point for binning is set. For instance if your bin size is 1, this value controls whether bin boundaries are at 0, 1, 2, .. or 0.5, 1.5, 2.5, ... etc. A value of 0 (or any integer) will result in a bin boundary at X=0 (linear X axis) or X=1 (logarithmic X axis). A fractional value will give a bin boundary at that value multiplied by the bin width. [Default: 0] thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 2] transparencyN = 0..1 (Double) Transparency with which components are plotted, in the range 0 (opaque) to 1 (invisible). The value is 1-alpha. [Default: 0] weightN = <num-expr> (String) Weighting of data points. If supplied, each point contributes a value to the histogram equal to the data value multiplied by this coordinate. If not supplied, the effect is the same as supplying a fixed value of one. The value is a numeric algebraic expression based on column names as described in Section 10. xN = <num-expr> (String) Horizontal coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.32 kde Plots a Discrete Kernel Density Estimate giving a smoothed frequency of data values along the horizontal axis, using a fixed-width smoothing kernel. This is a generalisation of a histogram in which the bins are always 1 pixel wide, and a smoothing kernel is applied to each bin. The width and shape of the kernel may be varied. This is suitable for cases where the division into discrete bins done by a normal histogram is unnecessary or troublesome. Note this is not a true Kernel Density Estimate, since, for performance reasons, the smoothing is applied to the (pixel-width) bins rather than to each data sample. The deviation from a true KDE caused by this quantisation will be at the pixel level, hence in most cases not visually apparent. A weighting may be applied to the calculated levels by supplying the weight coordinate. In this case you can choose how these weights are aggregated in each pixel bin using the combine parameter. The result is something like a smoothed version of the corresponding weighted histogram. Note that some combinations of the available parameters (e.g. a normalised cumulative median-aggregated KDE) may not make much visual sense. Usage Overview:  layerN=kde colorN=<rrggbb>|red|blue|... transparencyN=0..1 smoothN=+<width>|-<count> combineN=sum|sum-per-unit|count|... kernelN=square|linear|epanechnikov|cos|cos2|gauss3|gauss6 cumulativeN=none|forward|reverse normaliseN=none|area|unit|maximum|height fillN=solid|line|semi thickN=<pixels> xN=<num-expr> weightN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane ymin=0 layer1=kde in1=rrlyrae.fits x1=p1  colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] combineN = sum|sum-per-unit|count|... (Combiner) Defines how values contributing to the same bin are combined together to produce the value assigned to that bin, and hence its height. The bins in this case are 1-pixel wide, so lack much physical significance. This means that while some combination modes, such as sum-per-unit and mean make sense, others such as sum do not. The combined values are those given by the weight coordinate, but if no weight is supplied, a weighting of unity is assumed. The available options are: • sum: the sum of all the combined values per bin • sum-per-unit: the sum of all the combined values per unit of bin size • count: the number of non-blank values per bin (weight is ignored) • count-per-unit: the number of non-blank values per unit of bin size (weight is ignored) • mean: the mean of the combined values • median: the median • q1: first quartile • q3: third quartile • min: the minimum of all the combined values • max: the maximum of all the combined values • stdev: the sample standard deviation of the combined values • hit: 1 if any values present, NaN otherwise (weight is ignored) [Default: sum-per-unit] cumulativeN = none|forward|reverse (Cumulation) If set to forward/reverse the histogram bars plotted are calculated cumulatively; each bin includes the counts from all previous bins working up/down the independent axis. Note that setting cumulative plotting may not make much sense with some other parameter values, for instance averaging aggregation modes. For reasons of backward compatibility, the values true and false may be used as aliases for forward and none. The available options are: • none: The value plotted for each bin uses the samples accumulated in that bin. • forward: The value plotted for each bin uses the samples accumulated all the way from negative infinity to that bin. • reverse: The value plotted for each bin uses the samples accumulated all the way from positive infinity to that bin. [Default: none] fillN = solid|line|semi (FillMode) How the density function is represented. The available options are: • solid: area between level and axis is filled with solid colour • line: level is marked by a wiggly line • semi: level is marked by a wiggly line, and area below it is filled with a transparent colour [Default: semi] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] kernelN = square|linear|epanechnikov|cos|cos2|gauss3|gauss6 (Kernel1dShape) The functional form of the smoothing kernel. The functions listed refer to the unscaled shape; all kernels are normalised to give a total area of unity. The available options are: • square: Uniform value: f(x)=1, |x|=0..1 • linear: Triangle: f(x)=1-|x|, |x|=0..1 • epanechnikov: Parabola: f(x)=1-x*x, |x|=0..1 • cos: Cosine: f(x)=cos(x*pi/2), |x|=0..1 • cos2: Cosine squared: f(x)=cos^2(x*pi/2), |x|=0..1 • gauss3: Gaussian truncated at 3.0 sigma: f(x)=exp(-x*x/2), |x|=0..3 • gauss6: Gaussian truncated at 6.0 sigma: f(x)=exp(-x*x/2), |x|=0..6 [Default: epanechnikov] normaliseN = none|area|unit|maximum|height (Normalisation) Defines how, if at all, the bars of histogram-like plots are normalised or otherwise scaled vertically. Note that some of the normalisation options may not make much sense with some other parameter values, for instance averaging aggregation modes. The available options are: • none: No normalisation is performed. • area: The total area of histogram bars is normalised to unity. For cumulative plots, this behaves like height. • unit: Histogram bars are scaled by the inverse of the bin width in data units. For cumulative plots, this behaves like none. • maximum: The height of the tallest histogram bar is normalised to unity. For cumulative plots, this behaves like height. • height: The total height of histogram bars is normalised to unity. [Default: none] smoothN = +<width>|-<count> (BinSizer) Configures the smoothing width for kernel density estimation. This is the characteristic width of the kernel function to be convolved with the density to produce the visible plot. If the supplied value is a positive number it is interpreted as a fixed width in the data coordinates of the X axis (if the X axis is logarithmic, the value is a fixed factor). If it is a negative number, then it will be interpreted as the approximate number of smooothing widths that fit in the width of the visible plot (i.e. plot width / smoothing width). If the value is zero, no smoothing is applied. When setting this value graphically, you can use either the slider to adjust the bin count or the numeric entry field to fix the bin width. [Default: -100] thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 2] transparencyN = 0..1 (Double) Transparency with which components are plotted, in the range 0 (opaque) to 1 (invisible). The value is 1-alpha. [Default: 0] weightN = <num-expr> (String) Weighting of data points. If supplied, each point contributes a value to the histogram equal to the data value multiplied by this coordinate. If not supplied, the effect is the same as supplying a fixed value of one. The value is a numeric algebraic expression based on column names as described in Section 10. xN = <num-expr> (String) Horizontal coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.33 knn Plots a Discrete Kernel Density Estimate giving a smoothed frequency of data values along the horizontal axis, using an adaptive (K-Nearest-Neighbours) smoothing kernel. This is a generalisation of a histogram in which the bins are always 1 pixel wide, and a smoothing kernel is applied to each bin. The width and shape of the kernel may be varied. The K-Nearest-Neighbour figure gives the number of points in each direction to determine the width of the smoothing kernel for smoothing each bin. Upper and lower limits for the kernel width are also supplied; if the upper and lower limits are equal, this is equivalent to a fixed-width kernel. Note this is not a true Kernel Density Estimate, since, for performance reasons, the smoothing is applied to the (pixel-width) bins rather than to each data sample. The deviation from a true KDE caused by this quantisation will be at the pixel level, hence in most cases not visually apparent. Usage Overview:  layerN=knn colorN=<rrggbb>|red|blue|... transparencyN=0..1 knnN=<number> symmetricN=true|false minsmoothN=+<width>|-<count> maxsmoothN=+<width>|-<count> kernelN=square|linear|epanechnikov|cos|cos2|gauss3|gauss6 cumulativeN=none|forward|reverse normaliseN=none|area|unit|maximum|height fillN=solid|line|semi thickN=<pixels> xN=<num-expr> weightN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=knn in1=rrlyrae.fits x1=p1  colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] cumulativeN = none|forward|reverse (Cumulation) If set to forward/reverse the histogram bars plotted are calculated cumulatively; each bin includes the counts from all previous bins working up/down the independent axis. Note that setting cumulative plotting may not make much sense with some other parameter values, for instance averaging aggregation modes. For reasons of backward compatibility, the values true and false may be used as aliases for forward and none. The available options are: • none: The value plotted for each bin uses the samples accumulated in that bin. • forward: The value plotted for each bin uses the samples accumulated all the way from negative infinity to that bin. • reverse: The value plotted for each bin uses the samples accumulated all the way from positive infinity to that bin. [Default: none] fillN = solid|line|semi (FillMode) How the density function is represented. The available options are: • solid: area between level and axis is filled with solid colour • line: level is marked by a wiggly line • semi: level is marked by a wiggly line, and area below it is filled with a transparent colour [Default: semi] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] kernelN = square|linear|epanechnikov|cos|cos2|gauss3|gauss6 (Kernel1dShape) The functional form of the smoothing kernel. The functions listed refer to the unscaled shape; all kernels are normalised to give a total area of unity. The available options are: • square: Uniform value: f(x)=1, |x|=0..1 • linear: Triangle: f(x)=1-|x|, |x|=0..1 • epanechnikov: Parabola: f(x)=1-x*x, |x|=0..1 • cos: Cosine: f(x)=cos(x*pi/2), |x|=0..1 • cos2: Cosine squared: f(x)=cos^2(x*pi/2), |x|=0..1 • gauss3: Gaussian truncated at 3.0 sigma: f(x)=exp(-x*x/2), |x|=0..3 • gauss6: Gaussian truncated at 6.0 sigma: f(x)=exp(-x*x/2), |x|=0..6 [Default: epanechnikov] knnN = <number> (Double) Sets the number of nearest neighbours to count away from a sample point to determine the width of the smoothing kernel at that point. For the symmetric case this is the number of nearest neighbours summed over both directions, and for the asymmetric case it is the number in a single direction. The threshold is actually the weighted total of samples; for unweighted (weight=1) bins that is equivalent to the number of samples. [Default: 100] maxsmoothN = +<width>|-<count> (BinSizer) Fixes the maximum size of the smoothing kernel. This functions as an upper limit on the distance that is otherwise determined by searching for the K nearest neighbours at each sample point. If the supplied value is a positive number it is interpreted as a fixed width in the data coordinates of the X axis (if the X axis is logarithmic, the value is a fixed factor). If it is a negative number, then it will be interpreted as the approximate number of smooothing widths that fit in the width of the visible plot (i.e. plot width / smoothing width). If the value is zero, no smoothing is applied. When setting this value graphically, you can use either the slider to adjust the bin count or the numeric entry field to fix the bin width. [Default: -100] minsmoothN = +<width>|-<count> (BinSizer) Fixes the minimum size of the smoothing kernel. This functions as a lower limit on the distance that is otherwise determined by searching for the K nearest neighbours at each sample point. If the supplied value is a positive number it is interpreted as a fixed width in the data coordinates of the X axis (if the X axis is logarithmic, the value is a fixed factor). If it is a negative number, then it will be interpreted as the approximate number of smooothing widths that fit in the width of the visible plot (i.e. plot width / smoothing width). If the value is zero, no smoothing is applied. When setting this value graphically, you can use either the slider to adjust the bin count or the numeric entry field to fix the bin width. [Default: 0] normaliseN = none|area|unit|maximum|height (Normalisation) Defines how, if at all, the bars of histogram-like plots are normalised or otherwise scaled vertically. Note that some of the normalisation options may not make much sense with some other parameter values, for instance averaging aggregation modes. The available options are: • none: No normalisation is performed. • area: The total area of histogram bars is normalised to unity. For cumulative plots, this behaves like height. • unit: Histogram bars are scaled by the inverse of the bin width in data units. For cumulative plots, this behaves like none. • maximum: The height of the tallest histogram bar is normalised to unity. For cumulative plots, this behaves like height. • height: The total height of histogram bars is normalised to unity. [Default: none] symmetricN = true|false (Boolean) If true, the nearest neigbour search is carried out in both directions, and the kernel is symmetric. If false, the nearest neigbour search is carried out separately in the positive and negative directions, and the kernel width is accordingly different in the positive and negative directions. [Default: true] thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 2] transparencyN = 0..1 (Double) Transparency with which components are plotted, in the range 0 (opaque) to 1 (invisible). The value is 1-alpha. [Default: 0] weightN = <num-expr> (String) Weighting of data points. If supplied, each point contributes a value to the histogram equal to the data value multiplied by this coordinate. If not supplied, the effect is the same as supplying a fixed value of one. The value is a numeric algebraic expression based on column names as described in Section 10. xN = <num-expr> (String) Horizontal coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.34 densogram Represents smoothed density of data values along the horizontal axis using a colourmap. This is like a Kernel Density Estimate (smoothed histogram with bins 1 pixel wide), but instead of representing the data extent vertically as bars or a line, values are represented by a fixed-size pixel-width column of a colour from a colour map. A smoothing kernel, whose width and shape may be varied, is applied to each data point. A weighting may be applied to the calculated levels by supplying the weight coordinate. In this case you can choose how these weights are aggregated in each pixel bin using the combine parameter. The result is something like a smoothed version of the corresponding weighted histogram. Note that some combinations of the available parameters (e.g. a normalised cumulative median-aggregated KDE) may not make much visual sense. This is a rather unconventional way to represent density data, and this plotting mode is probably not very useful. But hey, nobody's forcing you to use it. Usage Overview:  layerN=densogram colorN=<rrggbb>|red|blue|... smoothN=+<width>|-<count> kernelN=square|linear|epanechnikov|cos|cos2|gauss3|gauss6 densemapN=<map-name>|<color>-<color>[-<color>...] denseclipN=<lo>,<hi> denseflipN=true|false densequantN=<number> densesubN=<lo>,<hi> densefuncN=log|linear|histogram|histolog|sqrt|square|acos|cos cumulativeN=none|forward|reverse sizeN=<pixels> posN=<fraction> xN=<num-expr> weightN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane in=tgas_source.fits x=hypot(pmra_error,pmdec_error) xlog=true normalise=maximum color=grey layer1=histogram layer2=kde layer3=densogram densemap3=skyblue-yellow-hotpink densefunc3=log size3=50 pos3=0.5  colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] cumulativeN = none|forward|reverse (Cumulation) If set to forward/reverse the histogram bars plotted are calculated cumulatively; each bin includes the counts from all previous bins working up/down the independent axis. Note that setting cumulative plotting may not make much sense with some other parameter values, for instance averaging aggregation modes. For reasons of backward compatibility, the values true and false may be used as aliases for forward and none. The available options are: • none: The value plotted for each bin uses the samples accumulated in that bin. • forward: The value plotted for each bin uses the samples accumulated all the way from negative infinity to that bin. • reverse: The value plotted for each bin uses the samples accumulated all the way from positive infinity to that bin. [Default: none] denseclipN = <lo>,<hi> (Subrange) Defines a subrange of the colour ramp to be used for Density shading. The value is specified as a (low,high) comma-separated pair of two numbers between 0 and 1. If the full range 0,1 is used, the whole range of colours specified by the selected shader will be used. But if for instance a value of 0,0.5 is given, only those colours at the left hand end of the ramp will be seen. If the null (default) value is chosen, a default clip will be used. This generally covers most or all of the range 0-1 but for colour maps which fade to white, a small proportion of the lower end may be excluded, to ensure that all the colours are visually distinguishable from a white background. This default is usually a good idea if the colour map is being used with something like a scatter plot, where markers are plotted against a white background. However, for something like a density map when the whole plotting area is tiled with colours from the map, it may be better to supply the whole range 0,1 explicitly. denseflipN = true|false (Boolean) If true, the colour map on the Density axis will be reversed. [Default: false] densefuncN = log|linear|histogram|histolog|sqrt|square|acos|cos (Scaling) Defines the way that values in the Density range are mapped to the selected colour ramp. The available options are: • log: Logarithmic scaling • linear: Linear scaling • histogram: Scaling follows data distribution, with linear axis • histolog: Scaling follows data distribution, with logarithmic axis • sqrt: Square root scaling • square: Square scaling • acos: Arccos Scaling • cos: Cos Scaling For all these options, the full range of data values is used, and displayed on the colour bar if applicable (though it can be restricted using the densesub option) The Linear, Log, Square and Sqrt options just apply the named function to the full data range. The histogram options on the other hand use a scaling function that corresponds to the actual distribution of the data, so that there are about the same number of points (or pixels, or whatever is being scaled) of each colour. The histogram options are somewhat more expensive, but can be a good choice if you are exploring data whose distribution is unknown or not well-behaved over its min-max range. The Histogram and HistoLog options both assign the colours in the same way, but they display the colour ramp with linear or logarithmic annotation respectively; the HistoLog option also ignores non-positive values. [Default: linear] densemapN = <map-name>|<color>-<color>[-<color>...] (Shader) Color map used for Density axis shading. A mixed bag of colour ramps are available as listed in Section 8.7: inferno, magma, plasma, viridis, cividis, cubehelix, sron, rainbow, rainbow2, rainbow3, pastel, cosmic, ember, gothic, rainforest, voltage, bubblegum, gem, chroma, neon, tropical, accent, gnuplot, gnuplot2, specxby, set1, paired, hotcold, guppy, iceburn, redshift, pride, rdbu, piyg, brbg, cyan-magenta, red-blue, brg, heat, cold, light, greyscale, colour, standard, bugn, bupu, orrd, pubu, purd, painbow, huecl, infinity, hue, intensity, rgb_red, rgb_green, rgb_blue, hsv_h, hsv_s, hsv_v, yuv_y, yuv_u, yuv_v, scale_hsv_s, scale_hsv_v, scale_yuv_y, mask, blacker, whiter, transparency. Note: many of these, including rainbow-like ones, are frowned upon by the visualisation community. You can also construct your own custom colour map by giving a sequence of colour names separated by minus sign ("-") characters. In this case the ramp is a linear interpolation between each pair of colours named, using the same syntax as when specifying a colour value. So for instance "yellow-hotpink-#0000ff" would shade from yellow via hot pink to blue. [Default: inferno] densequantN = <number> (Double) Allows the colour map used for the Density axis to be quantised. If an integer value N is chosen then the colour map will be viewed as N discrete evenly-spaced levels, so that only N different colours will appear in the plot. This can be used to generate a contour-like effect, and may make it easier to trace the boundaries of regions of interest by eye. If left blank, the colour map is nominally continuous (though in practice it may be quantised to a medium-sized number like 256). densesubN = <lo>,<hi> (Subrange) Defines a normalised adjustment to the data range of the Density axis. The value may be specified as a comma-separated pair of two numbers, giving the lower and upper bounds of the range of of interest respectively. This sub-range is applied to the data range that would otherwise be used, either automatically calculated or explicitly supplied; zero corresponds to the lower bound and one to the upper. The default value "0,1" therefore has no effect. The range could be restricted to its lower half with the value 0,0.5. [Default: 0,1] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] kernelN = square|linear|epanechnikov|cos|cos2|gauss3|gauss6 (Kernel1dShape) The functional form of the smoothing kernel. The functions listed refer to the unscaled shape; all kernels are normalised to give a total area of unity. The available options are: • square: Uniform value: f(x)=1, |x|=0..1 • linear: Triangle: f(x)=1-|x|, |x|=0..1 • epanechnikov: Parabola: f(x)=1-x*x, |x|=0..1 • cos: Cosine: f(x)=cos(x*pi/2), |x|=0..1 • cos2: Cosine squared: f(x)=cos^2(x*pi/2), |x|=0..1 • gauss3: Gaussian truncated at 3.0 sigma: f(x)=exp(-x*x/2), |x|=0..3 • gauss6: Gaussian truncated at 6.0 sigma: f(x)=exp(-x*x/2), |x|=0..6 [Default: epanechnikov] posN = <fraction> (Double) Determines where on the plot region the density bar appears. The value should be in the range 0..1; zero corresponds to the bottom of the plot and one to the top. [Default: 0.05] sizeN = <pixels> (Integer) Height of the density bar in pixels. [Default: 12] smoothN = +<width>|-<count> (BinSizer) Configures the smoothing width for kernel density estimation. This is the characteristic width of the kernel function to be convolved with the density to produce the visible plot. If the supplied value is a positive number it is interpreted as a fixed width in the data coordinates of the X axis (if the X axis is logarithmic, the value is a fixed factor). If it is a negative number, then it will be interpreted as the approximate number of smooothing widths that fit in the width of the visible plot (i.e. plot width / smoothing width). If the value is zero, no smoothing is applied. When setting this value graphically, you can use either the slider to adjust the bin count or the numeric entry field to fix the bin width. [Default: -100] weightN = <num-expr> (String) Weighting of data points. If supplied, each point contributes a value to the histogram equal to the data value multiplied by this coordinate. If not supplied, the effect is the same as supplying a fixed value of one. The value is a numeric algebraic expression based on column names as described in Section 10. xN = <num-expr> (String) Horizontal coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.35 gaussian Plots a best fit Gaussian to the histogram of a sample of data. In fact, all this plotter does is to calculate the mean and standard deviation of the sample, and plot the corresponding Gaussian curve. The mean and standard deviation values are reported by the plot. The normalise config option, perhaps in conjunction with binsize, can be used to scale the height of the plotted curve in data units. In this case, binsize just describes the bar width of a notional histogram whose outline the plotted Gaussian should try to fit, and is only relevant for some of the normalisation options. Usage Overview:  layerN=gaussian colorN=<rrggbb>|red|blue|... showmeanN=true|false thickN=<pixels> dashN=dot|dash|...|<a,b,...> antialiasN=true|false normaliseN=none|area|unit|maximum|height binsizeN=+<width>|-<count> xN=<num-expr> weightN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane in=mgc_ok.fits x=mgc_dc_sb layer1=histogram color1=green layer2=gaussian color2=grey thick2=3 ymax=1200 antialiasN = true|false (Boolean) If true, plotted lines are drawn with antialising. Antialised lines look smoother, but may take perceptibly longer to draw. Only has any effect for bitmapped output formats. [Default: false] binsizeN = +<width>|-<count> (BinSizer) Configures the width of histogram bins. If the supplied string is a positive number, it is interpreted as a fixed width in the data coordinates of the X axis (if the X axis is logarithmic, the value is a fixed factor). If it is a negative number, then it will be interpreted as the approximate number of bins to display across the width of the plot (though an attempt is made to use only round numbers for bin widths). When setting this value graphically, you can use either the slider to adjust the bin count or the numeric entry field to fix the bin width. [Default: -30] colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] dashN = dot|dash|...|<a,b,...> (float[]) Determines the dash pattern of the line drawn. If null (the default), the line is solid. Possible values for dashed lines are dot, dash, longdash, dotdash. You can alternatively supply a comma-separated list of on/off length values such as "4,2,8,2". icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] normaliseN = none|area|unit|maximum|height (Normalisation) Defines how, if at all, the bars of histogram-like plots are normalised or otherwise scaled vertically. Note that some of the normalisation options may not make much sense with some other parameter values, for instance averaging aggregation modes. The available options are: • none: No normalisation is performed. • area: The total area of histogram bars is normalised to unity. For cumulative plots, this behaves like height. • unit: Histogram bars are scaled by the inverse of the bin width in data units. For cumulative plots, this behaves like none. • maximum: The height of the tallest histogram bar is normalised to unity. For cumulative plots, this behaves like height. • height: The total height of histogram bars is normalised to unity. [Default: none] showmeanN = true|false (Boolean) If true, a line is drawn at the position of the calculated mean. [Default: true] thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 1] weightN = <num-expr> (String) Weighting of data points. If supplied, each point contributes a value to the histogram equal to the data value multiplied by this coordinate. If not supplied, the effect is the same as supplying a fixed value of one. The value is a numeric algebraic expression based on column names as described in Section 10. xN = <num-expr> (String) Horizontal coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.36 function Plots an analytic function. This layer is currently only available for the Plane plots (including histogram). Usage Overview:  layerN=function axisN=Horizontal|Vertical xnameN=<name> fexprN=<expr> colorN=<rrggbb>|red|blue|... thickN=<pixels> dashN=dot|dash|...|<a,b,...> antialiasN=true|false  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=function fexpr1=sin(x)/x thick1=3 xmin=0 xmax=30 ymin=-0.25 ymax=0.25 antialiasN = true|false (Boolean) If true, plotted lines are drawn with antialising. Antialised lines look smoother, but may take perceptibly longer to draw. Only has any effect for bitmapped output formats. [Default: false] axisN = Horizontal|Vertical (FuncAxis) Which axis the independent variable varies along. Options are currently Horizontal and Vertical. [Default: Horizontal] colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] dashN = dot|dash|...|<a,b,...> (float[]) Determines the dash pattern of the line drawn. If null (the default), the line is solid. Possible values for dashed lines are dot, dash, longdash, dotdash. You can alternatively supply a comma-separated list of on/off length values such as "4,2,8,2". fexprN = <expr> (String) An expression using TOPCAT's expression language in terms of the independent variable to define the function. This expression must be standalone - it cannot reference any tables. thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 1] xnameN = <name> (String) Name of the independent variable for use in the function expression. This is typically x for a horizontal independent variable and y for a vertical independent variable, but any string that is a legal expression language identifier (starts with a letter, continues with letters, numbers, underscores) can be used. [Default: x] #### 8.3.37 skyvector Plots directed lines from the data position given delta values for the coordinates The plotted markers are typically little arrows, but there are other options. The dimensions of the plotted vectors are given by the dlon and dlat coordinates. The units of these values are specified using the unit option. If only the relative rather than the absolute sizes are required on the plot, or if the units are not known, the special value unit=scaled may be used; this applies a non-physical scaling factor to make the vectors appear at some reasonable size in the plot. When unit=scaled vectors will keep approximately the same screen size during zoom operations; when one of the angular units is chosen, they will keep the same size in data coordinates. Additionally, the scale option may be used to scale all the plotted vectors by a given factor to make them all larger or smaller. Usage Overview:  layerN=skyvector arrowN=small_arrow|medium_arrow|... thickN=<int-value> unitN=scaled|radian|degree|minute|arcsec|mas|uas scaleN=<number> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> lonN=<deg-expr> latN=<deg-expr> dlonN=<num-expr> dlatN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2sky in=tgas_source.fits lon=ra lat=dec layer1=mark layer2=skyvector dlon2=pmra dlat2=pmdec unit2=scaled arrow2=medium_arrow clon=56.75 clat=24.10 radius=1.5 arrowN = small_arrow|medium_arrow|... (MultiPointShape) How arrows are represented. The available options are: • small_arrow • medium_arrow • large_arrow • small_open_dart • medium_open_dart • large_open_dart • small_filled_dart • medium_filled_dart • large_filled_dart • lines • capped_lines [Default: small_arrow] dlatN = <num-expr> (String) Change in the latitude coordinate represented by the plotted vector. The units of this angular extent are determined by the unit option. The value is a numeric algebraic expression based on column names as described in Section 10. dlonN = <num-expr> (String) Change in the longitude coordinate represented by the plotted vector. The supplied value is considered to be premultiplied by cos(Latitude). The units of this angular extent are determined by the unit option. The value is a numeric algebraic expression based on column names as described in Section 10. icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] latN = <deg-expr> (String) Latitude in decimal degrees. The value is a numeric algebraic expression based on column names as described in Section 10. lonN = <deg-expr> (String) Longitude in decimal degrees. The value is a numeric algebraic expression based on column names as described in Section 10. scaleN = <number> (Double) Scales the size of variable-sized markers like vectors and ellipses. The default value is 1, smaller or larger values multiply the visible sizes accordingly. The main purpose of this option is to tweak the visible sizes of the plotted markers for better visibility. The unit option is more convenient to account for the units in which the angular extent coordinates are supplied. If the markers are supposed to be plotted with their absolute angular extents visible, this option should be set to its default value of 1. [Default: 1] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] unitN = scaled|radian|degree|minute|arcsec|mas|uas (AngleUnit) Defines the units in which the angular extents are specified. Options are degrees, arcseconds etc. If the special value scaled is given then a non-physical scaling is applied to the input values to make the the largest markers appear at a reasonable size (a few tens of pixels) in the plot. Note that the actual plotted size of the markers can also be scaled using the scale option; these two work together to determine the actual plotted sizes. The available options are: • scaled: a non-physical scaling is applied based on the size of values present • radian: radians • degree: degrees • minute: arcminutes • arcsec: arcseconds • mas: milli-arcseconds • uas: micro-arcseconds [Default: degree] #### 8.3.38 skyellipse Plots an ellipse (or rectangle, triangle, or other similar figure) defined by two principal radii and an optional angle of rotation, the so-called position angle. This angle, if specified, is in degrees and gives the angle from the North pole towards the direction of increasing longitude on the longitude axis. The dimensions of the plotted ellipses are given by the ra and rb coordinates. The units of these values are specified using the unit option. If only the relative rather than the absolute sizes are required on the plot, or if the units are not known, the special value unit=scaled may be used; this applies a non-physical scaling factor to make the ellipses appear at some reasonable size in the plot. When unit=scaled ellipses will keep approximately the same screen size during zoom operations; when one of the angular units is chosen, they will keep the same size in data coordinates. Additionally, the scale option may be used to scale all the plotted ellipses by a given factor to make them all larger or smaller. Usage Overview:  layerN=skyellipse ellipseN=ellipse|crosshair_ellipse|... thickN=<int-value> unitN=scaled|radian|degree|minute|arcsec|mas|uas scaleN=<number> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> lonN=<deg-expr> latN=<deg-expr> raN=<num-expr> rbN=<num-expr> posangN=<deg-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2sky in=mgc_ok.fits lon=mgc_alpha_j2000 lat=mgc_delta_j2000 ra=bulge_re rb=bulge_re*bulge_e unit=arcsec posang=bulge_pa scale=10 color=#cc00ff layer1=skyellipse ellipse1=filled_ellipse shading1=transparent opaque1=4 layer2=skyellipse ellipse2=crosshair_ellipse clon=180.1 clat=0 radius=0.25 ellipseN = ellipse|crosshair_ellipse|... (MultiPointShape) How ellipses are represented. The available options are: • ellipse • crosshair_ellipse • filled_ellipse • rectangle • crosshair_rectangle • filled_rectangle • open_triangle • filled_triangle • lines • capped_lines • arrows [Default: ellipse] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] latN = <deg-expr> (String) Latitude in decimal degrees. The value is a numeric algebraic expression based on column names as described in Section 10. lonN = <deg-expr> (String) Longitude in decimal degrees. The value is a numeric algebraic expression based on column names as described in Section 10. posangN = <deg-expr> (String) Orientation of the ellipse. The value is the angle in degrees from the North pole to the primary axis of the ellipse in the direction of increasing longitude. The value is a numeric algebraic expression based on column names as described in Section 10. raN = <num-expr> (String) Ellipse first principal radius. The units of this angular extent are determined by the unit option. The value is a numeric algebraic expression based on column names as described in Section 10. rbN = <num-expr> (String) Ellipse second principal radius. The units of this angular extent are determined by the unit option. If this value is blank, the two radii will be assumed equal, i.e. the ellipses will be circles. The value is a numeric algebraic expression based on column names as described in Section 10. scaleN = <number> (Double) Scales the size of variable-sized markers like vectors and ellipses. The default value is 1, smaller or larger values multiply the visible sizes accordingly. The main purpose of this option is to tweak the visible sizes of the plotted markers for better visibility. The unit option is more convenient to account for the units in which the angular extent coordinates are supplied. If the markers are supposed to be plotted with their absolute angular extents visible, this option should be set to its default value of 1. [Default: 1] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] unitN = scaled|radian|degree|minute|arcsec|mas|uas (AngleUnit) Defines the units in which the angular extents are specified. Options are degrees, arcseconds etc. If the special value scaled is given then a non-physical scaling is applied to the input values to make the the largest markers appear at a reasonable size (a few tens of pixels) in the plot. Note that the actual plotted size of the markers can also be scaled using the scale option; these two work together to determine the actual plotted sizes. The available options are: • scaled: a non-physical scaling is applied based on the size of values present • radian: radians • degree: degrees • minute: arcminutes • arcsec: arcseconds • mas: milli-arcseconds • uas: micro-arcseconds [Default: degree] #### 8.3.39 skycorr Plots an error ellipse (or rectangle or other similar figure) on the sky defined by errors in the longitude and latitude directions, and a correlation between the two errors. The error in longitude is considered to be premultiplied by the cosine of the latitude, i.e. both errors correspond to angular distances along a great circle. The supplied correlation is a dimensionless value in the range -1..+1 and is equal to the covariance divided by the product of the lon and lat errors. The covariance matrix is thus:  [ lonerr*lonerr lonerr*laterr*corr ] [ lonerr*laterr*corr laterr*laterr ]  The dimensions of the plotted ellipses are given by the lonerr and laterr coordinates. The units of these values are specified using the unit option. If only the relative rather than the absolute sizes are required on the plot, or if the units are not known, the special value unit=scaled may be used; this applies a non-physical scaling factor to make the ellipses appear at some reasonable size in the plot. When unit=scaled ellipses will keep approximately the same screen size during zoom operations; when one of the angular units is chosen, they will keep the same size in data coordinates. Additionally, the scale option may be used to scale all the plotted ellipses by a given factor to make them all larger or smaller. This plot type is suitable for use with the ra_error, dec_error and ra_dec_corr columns in the Gaia source catalogue. Note that Gaia positional errors are generally quoted in milli-arcseconds, so you should set unit=mas. Note also that in most plots Gaia positional errors are much too small to see! Usage Overview:  layerN=skycorr ellipseN=ellipse|crosshair_ellipse|... thickN=<int-value> unitN=scaled|radian|degree|minute|arcsec|mas|uas scaleN=<number> shadingN=auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> lonN=<deg-expr> latN=<deg-expr> lonerrN=<num-expr> laterrN=<num-expr> corrN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2sky in=tgas_source.fits lon=ra lat=dec icmd='select ra>245.1&&ra<245.9&&dec>-17.8&&dec<-17.2' color=blue layer1=mark unit=mas scale=2e5 ra2=ra_error rb2=dec_error posang2=90 color2=orange shading2=transparent layer2a=skyellipse ellipse2a=filled_rectangle opaque2a=6 layer2b=skyellipse ellipse2b=crosshair_rectangle opaque2b=2 layer3=skycorr lonerr3=ra_error laterr3=dec_error corr3=ra_dec_corr ellipse3=crosshair_ellipse  corrN = <num-expr> (String) Correlation between the errors in longitude and latitude. This is a dimensionless quantity in the range -1..+1, and is equivalent to the covariance divided by the product of the Longitude and Latitude error values themselves. It corresponds to the ra_dec_corr value supplied in the Gaia source catalogue. The value is a numeric algebraic expression based on column names as described in Section 10. ellipseN = ellipse|crosshair_ellipse|... (MultiPointShape) How ellipses are represented. The available options are: • ellipse • crosshair_ellipse • filled_ellipse • rectangle • crosshair_rectangle • filled_rectangle • open_triangle • filled_triangle • lines • capped_lines • arrows [Default: ellipse] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] latN = <deg-expr> (String) Latitude in decimal degrees. The value is a numeric algebraic expression based on column names as described in Section 10. laterrN = <num-expr> (String) Error in the latitude coordinate. The units of this angular extent are determined by the unit option. The value is a numeric algebraic expression based on column names as described in Section 10. lonN = <deg-expr> (String) Longitude in decimal degrees. The value is a numeric algebraic expression based on column names as described in Section 10. lonerrN = <num-expr> (String) Error in the longitude coordinate. The supplied value is considered to be premultiplied by cos(Latitude). The units of this angular extent are determined by the unit option. The value is a numeric algebraic expression based on column names as described in Section 10. scaleN = <number> (Double) Scales the size of variable-sized markers like vectors and ellipses. The default value is 1, smaller or larger values multiply the visible sizes accordingly. The main purpose of this option is to tweak the visible sizes of the plotted markers for better visibility. The unit option is more convenient to account for the units in which the angular extent coordinates are supplied. If the markers are supposed to be plotted with their absolute angular extents visible, this option should be set to its default value of 1. [Default: 1] shadingN = auto|flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • auto • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: auto] thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] unitN = scaled|radian|degree|minute|arcsec|mas|uas (AngleUnit) Defines the units in which the angular extents are specified. Options are degrees, arcseconds etc. If the special value scaled is given then a non-physical scaling is applied to the input values to make the the largest markers appear at a reasonable size (a few tens of pixels) in the plot. Note that the actual plotted size of the markers can also be scaled using the scale option; these two work together to determine the actual plotted sizes. The available options are: • scaled: a non-physical scaling is applied based on the size of values present • radian: radians • degree: degrees • minute: arcminutes • arcsec: arcseconds • mas: milli-arcseconds • uas: micro-arcseconds [Default: degree] #### 8.3.40 skydensity Plots a density map on the sky. The grid on which the values are drawn uses the HEALPix tesselation, with a configurable resolution. You can optionally use a weighting for the points, and you can configure how the points are combined to produce the output pixel values. The way that data values are mapped to colours is usually controlled by options at the level of the plot itself, rather than by per-layer configuration. Usage Overview:  layerN=skydensity levelN=<-rel-level|+abs-level> combineN=sum|sum-per-unit|count|... perunitN=steradian|degree2|arcmin2|arcsec2|mas2|uas2 transparencyN=0..1 lonN=<deg-expr> latN=<deg-expr> weightN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2sky in=tgas_source.fits lon=l lat=b layer1=skydensity weight1=parallax combine1=mean level1=4 projection=aitoff auxmap=PuRd auxfunc=histogram xpix=540 ypix=250 combineN = sum|sum-per-unit|count|... (Combiner) Defines how values contributing to the same density map bin are combined together to produce the value assigned to that bin, and hence its colour. The combined values are the weights, but if the weight is left blank, a weighting of unity is assumed. For density-like values (count-per-unit, sum-per-unit) the scaling is additionally influenced by the perunit parameter. The available options are: • sum: the sum of all the combined values per bin • sum-per-unit: the sum of all the combined values per unit of bin size • count: the number of non-blank values per bin (weight is ignored) • count-per-unit: the number of non-blank values per unit of bin size (weight is ignored) • mean: the mean of the combined values • median: the median • q1: first quartile • q3: third quartile • min: the minimum of all the combined values • max: the maximum of all the combined values • stdev: the sample standard deviation of the combined values • hit: 1 if any values present, NaN otherwise (weight is ignored) [Default: sum-per-unit] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] latN = <deg-expr> (String) Latitude in decimal degrees. The value is a numeric algebraic expression based on column names as described in Section 10. levelN = <-rel-level|+abs-level> (Integer) Determines the HEALPix level of pixels which are averaged over to calculate density. If the supplied value is a non-negative integer, it gives the absolute level to use; at level 0 there are 12 pixels on the sky, and the count multiplies by 4 for each increment. If the value is negative, it represents a relative level; it is approximately the (negative) number of screen pixels along one side of a HEALPix sky pixel. In this case the actual HEALPix level will depend on the current zoom. [Default: -3] lonN = <deg-expr> (String) Longitude in decimal degrees. The value is a numeric algebraic expression based on column names as described in Section 10. perunitN = steradian|degree2|arcmin2|arcsec2|mas2|uas2 (SolidAngleUnit) Defines the unit of sky area used for scaling density-like combinations (e.g. combine=count-per-unit or sum-per-unit). If the Combination mode is calculating values per unit area, this configures the area scale in question. For non-density-like combination modes (e.g. combine=sum or mean) it has no effect. The available options are: • steradian: (180/Pi)^2 deg^2 • degree2: square degrees • arcmin2: square arcminute, (1/60)^2 deg^2 • arcsec2: square arcsecond, (1/3600)^2 deg^2 • mas2: square milliarcsecond, (.001/3600)^2 deg^2 • uas2: square microarcsecond, (1e-6/3600)^2 deg^2 [Default: degree2] transparencyN = 0..1 (Double) Transparency with which components are plotted, in the range 0 (opaque) to 1 (invisible). The value is 1-alpha. [Default: 0] weightN = <num-expr> (String) Weighting of data points. If supplied, each point contributes a value to the histogram equal to the data value multiplied by this coordinate. If not supplied, the effect is the same as supplying a fixed value of one. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.41 healpix Plots a table representing HEALPix pixels on the sky. Each row represents a single HEALPix tile, and a value from that row is used to colour the corresponding region of the sky plot. The way that data values are mapped to colours is usually controlled by options at the level of the plot itself, rather than by per-layer configuration. Usage Overview:  layerN=healpix datalevelN=<int-value> datasysN=<value> viewsysN=equatorial|galactic|supergalactic|ecliptic degradeN=<int-value> combineN=sum|sum-per-unit|count|... perunitN=steradian|degree2|arcmin2|arcsec2|mas2|uas2 transparencyN=0..1 healpixN=<num-expr> valueN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2sky layer1=healpix in1=simbad-hpx8.fits healpix1=HPX8 value1=NBREF datalevel1=8 degrade1=2 combine=sum-per-unit perunit=arcmin2 projection=aitoff datasys1=equatorial viewsys=galactic labelpos=none auxfunc=log auxmap=cold auxflip=true auxclip=0,1 xpix=600 ypix=280 combineN = sum|sum-per-unit|count|... (Combiner) Defines how values degraded to a lower HEALPix level are combined together to produce the value assigned to the larger tile, and hence its colour. This is mostly useful in the case that degrade>0. For density-like values (count-per-unit, sum-per-unit) the scaling is additionally influenced by the perunit parameter. The available options are: • sum: the sum of all the combined values per bin • sum-per-unit: the sum of all the combined values per unit of bin size • count: the number of non-blank values per bin (weight is ignored) • count-per-unit: the number of non-blank values per unit of bin size (weight is ignored) • mean: the mean of the combined values • median: the median • q1: first quartile • q3: third quartile • min: the minimum of all the combined values • max: the maximum of all the combined values • stdev: the sample standard deviation of the combined values • hit: 1 if any values present, NaN otherwise (weight is ignored) [Default: mean] datalevelN = <int-value> (Integer) HEALPix level of the (implicit or explicit) tile indices. Legal values are between 0 (12 pixels) and 29 (3458764513820540928 pixels). If a negative value is supplied (the default), then an attempt is made to determine the correct level from the data. [Default: -1] datasysN = <value> (SkySys) The sky coordinate system to which the HEALPix grid used by the input pixel file refers. [Default: equatorial] degradeN = <int-value> (Integer) Allows the HEALPix grid to be drawn at a less detailed level than the level at which the input data are supplied. A value of zero (the default) means that the HEALPix tiles are painted with the same resolution as the input data, but a higher value will degrade resolution of the plot tiles; each plotted tile will correspond to 4^degrade input tiles. The way that values are combined within each painted tile is controlled by the combine value. [Default: 0] healpixN = <num-expr> (String) HEALPix index indicating the sky position of the tile whose value is plotted. If not supplied, the assumption is that the supplied table contains one row for each HEALPix tile at a given level, in ascending order. The value is a numeric algebraic expression based on column names as described in Section 10. icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] perunitN = steradian|degree2|arcmin2|arcsec2|mas2|uas2 (SolidAngleUnit) Defines the unit of sky area used for scaling density-like combinations (e.g. combine=count-per-unit or sum-per-unit). If the Combination mode is calculating values per unit area, this configures the area scale in question. For non-density-like combination modes (e.g. combine=sum or mean) it has no effect. The available options are: • steradian: (180/Pi)^2 deg^2 • degree2: square degrees • arcmin2: square arcminute, (1/60)^2 deg^2 • arcsec2: square arcsecond, (1/3600)^2 deg^2 • mas2: square milliarcsecond, (.001/3600)^2 deg^2 • uas2: square microarcsecond, (1e-6/3600)^2 deg^2 [Default: degree2] transparencyN = 0..1 (Double) Transparency with which components are plotted, in the range 0 (opaque) to 1 (invisible). The value is 1-alpha. [Default: 0] valueN = <num-expr> (String) Value of HEALPix tile, determining the colour which will be plotted. The value is a numeric algebraic expression based on column names as described in Section 10. viewsysN = equatorial|galactic|supergalactic|ecliptic (SkySys) The sky coordinate system used for the generated plot. Choice of this value goes along with the data coordinate system that may be specified for plot layers. If unspecified, a generic longitude/latitude system is used, and all lon/lat coordinates in the plotted data layers are assumed to be in the same system. If a value is supplied for this parameter, then a sky system must (implicitly or explicitly) be supplied for each data layer, and the coordinates are converted from data to view system before being plotted. The available options are: • equatorial: J2000 equatorial system • galactic: IAU 1958 galactic system • supergalactic: De Vaucouleurs supergalactic system • ecliptic: ecliptic system based on conversion at 2000.0 [Default: equatorial] #### 8.3.42 skygrid Plots an additional axis grid on the celestial sphere. This can be overlaid on the default sky axis grid so that axes for multiple sky coordinate systems are simultaneously visible. The plots are done relative to the View sky system (viewsys parameter) defined for the plot as a whole. Note that some of the configuration items for this plotter, such as grid line antialiasing and the decimal/sexagesimal flag, are inherited from the values set for the main sky plot grid. Usage Overview:  layerN=skygrid gridsysN=equatorial|galactic|supergalactic|ecliptic gridcolorN=<rrggbb>|red|blue|... transparencyN=0..1 labelposN=Internal|None loncrowdN=<number> latcrowdN=<number>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2sky xpix=500 ypix=250 projection=aitoff viewsys=equatorial labelpos=none sex=false layer1=skygrid gridsys1=ecliptic gridcolor1=HotPink labelpos1=internal  gridcolorN = <rrggbb>|red|blue|... (Color) The color of the plot grid, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: light_grey] gridsysN = equatorial|galactic|supergalactic|ecliptic (SkySys) The sky coordinate system used for the additional grid axes. This is used in conunction with the viewsys parameter defined for the plot as a whole to determin what grid lines to plot. The available options are: • equatorial: J2000 equatorial system • galactic: IAU 1958 galactic system • supergalactic: De Vaucouleurs supergalactic system • ecliptic: ecliptic system based on conversion at 2000.0 [Default: equatorial] labelposN = Internal|None (SkyAxisLabeller) Controls how and whether the numeric annotations of the lon/lat axes are displayed. The available options are: • Internal: Labels are drawn inside the plot bounds • None: Axes are not labelled [Default: Internal] latcrowdN = <number> (Double) Determines how closely sky latitude grid lines (parallels) are spaced. The default value is 1, meaning normal crowding. Larger values result in more grid lines, and smaller values in fewer grid lines. [Default: 1] loncrowdN = <number> (Double) Determines how closely sky longitude grid lines (meridians) are spaced. The default value is 1, meaning normal crowding. Larger values result in more grid lines, and smaller values in fewer grid lines. [Default: 1] transparencyN = 0..1 (Double) Transparency with which components are plotted, in the range 0 (opaque) to 1 (invisible). The value is 1-alpha. [Default: 0] #### 8.3.43 xyzvector Plots directed lines from the data position given delta values for the coordinates. The plotted markers are typically little arrows, but there are other options. In some cases the supplied data values give the actual extents in data coordinates for the plotted vectors but sometimes the data is on a different scale or in different units to the positional coordinates. As a convenience for this case, the plotter can optionally scale the magnitudes of all the vectors to make them a reasonable size on the plot, so by default the largest ones are a few tens of pixels long. This auto-scaling is turned off by default, but it can be activated with the autoscale option. Whether autoscaling is on or off, the scale option can be used to apply a fixed scaling factor. Usage Overview:  layerN=xyzvector arrowN=small_arrow|medium_arrow|... thickN=<int-value> scaleN=<factor> autoscaleN=true|false shadingN=flat|translucent|transparent|density|aux|weighted <shade-paramsN> xN=<num-expr> yN=<num-expr> zN=<num-expr> xdeltaN=<num-expr> ydeltaN=<num-expr> zdeltaN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2cube in=gavo_g2.fits x=x y=y z=z xdelta=velX ydelta=velY zdelta=velZ autoscale=true color=BlueViolet scale=1.5 layer1=xyzvector shading1=transparent opaque1=5 arrow1=medium_filled_dart layer2=xyzvector shading2=flat arrow2=medium_open_dart xmin=6 xmax=7.5 ymin=12.5 ymax=13.5 zmin=19 zmax=21.5 arrowN = small_arrow|medium_arrow|... (MultiPointShape) How arrows are represented. The available options are: • small_arrow • medium_arrow • large_arrow • small_open_dart • medium_open_dart • large_open_dart • small_filled_dart • medium_filled_dart • large_filled_dart • lines • capped_lines [Default: small_arrow] autoscaleN = true|false (Boolean) Determines whether the default size of variable-sized markers like vectors and ellipses are automatically scaled to have a sensible size. If true, then the sizes of all the plotted markers are examined, and some dynamically calculated factor is applied to them all to make them a sensible size (by default, the largest ones will be a few tens of pixels). If false, the sizes will be the actual input values interpreted in data coordinates. If auto-scaling is on, then markers will keep approximately the same screen size during zoom operations; if it's off, they will keep the same size in data coordinates. Marker size is also affected by the scale parameter. [Default: false] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] scaleN = <factor> (Double) Affects the size of variable-sized markers like vectors and ellipses. The default value is 1, smaller or larger values multiply the visible sizes accordingly. [Default: 1] shadingN = flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: flat] thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] xN = <num-expr> (String) X coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. xdeltaN = <num-expr> (String) Vector component in the X direction. The value is a numeric algebraic expression based on column names as described in Section 10. yN = <num-expr> (String) Y coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. ydeltaN = <num-expr> (String) Vector component in the Y direction. The value is a numeric algebraic expression based on column names as described in Section 10. zN = <num-expr> (String) Z coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. zdeltaN = <num-expr> (String) Vector component in the Z direction. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.44 xyzerror Plots symmetric or asymmetric error bars in some or all of the plot dimensions. The shape of the error "bars" is quite configurable, including (for 2-d and 3-d errors) ellipses, rectangles etc aligned with the axes. Usage Overview:  layerN=xyzerror errorbarN=none|lines|capped_lines|... thickN=<int-value> shadingN=flat|translucent|transparent|density|aux|weighted <shade-paramsN> xN=<num-expr> yN=<num-expr> zN=<num-expr> xerrhiN=<num-expr> xerrloN=<num-expr> yerrhiN=<num-expr> yerrloN=<num-expr> zerrhiN=<num-expr> zerrloN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2cube in=dr5qso.fits icmd='select morphology==1' x=psfmag_g xerrhi=psfmagerr_g y=psfmag_r yerrhi=psfmagerr_r z=psfmag_u zerrhi=psfmagerr_u layer1=mark layer2=xyzerror errorbar2=cuboid shading=transparent opaque=3 xmin=17.5 xmax=18 ymin=17.3 ymax=17.7 zmin=17.4 zmax=18.2 errorbarN = none|lines|capped_lines|... (MultiPointShape) How errorbars are represented. The available options are: • none • lines • capped_lines • caps • arrows • cuboid • ellipse • crosshair_ellipse • rectangle • crosshair_rectangle • filled_ellipse • filled_rectangle [Default: lines] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] shadingN = flat|translucent|transparent|density|aux|weighted <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • flat • translucent • transparent • density • aux • weighted Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: flat] thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] xN = <num-expr> (String) X coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. xerrhiN = <num-expr> (String) Error in the X coordinate in the positive direction. If no corresponding negative error value is supplied, then this value is also used in the negative direction, i.e. in that case errors are assumed to be symmetric. The value is a numeric algebraic expression based on column names as described in Section 10. xerrloN = <num-expr> (String) Error in the X coordinate in the negative direction. If left blank, it is assumed to take the same value as the positive error. The value is a numeric algebraic expression based on column names as described in Section 10. yN = <num-expr> (String) Y coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. yerrhiN = <num-expr> (String) Error in the Y coordinate in the positive direction. If no corresponding negative error value is supplied, then this value is also used in the negative direction, i.e. in that case errors are assumed to be symmetric. The value is a numeric algebraic expression based on column names as described in Section 10. yerrloN = <num-expr> (String) Error in the Y coordinate in the negative direction. If left blank, it is assumed to take the same value as the positive error. The value is a numeric algebraic expression based on column names as described in Section 10. zN = <num-expr> (String) Z coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. zerrhiN = <num-expr> (String) Error in the Z coordinate in the positive direction. If no corresponding negative error value is supplied, then this value is also used in the negative direction, i.e. in that case errors are assumed to be symmetric. The value is a numeric algebraic expression based on column names as described in Section 10. zerrloN = <num-expr> (String) Error in the Z coordinate in the negative direction. If left blank, it is assumed to take the same value as the positive error. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.45 line3d Plots a point-to-point line joining up the positions of data points in three dimensions. There are additional options to pre-sort the points by a given quantity before drawing the lines (using the sort value), and to vary the colour of the line along its length (using the aux value). The options for controlling the Aux colour map are controlled at the level of the plot itself, rather than by per-layer configuration. Note that the line positioning in 3d and the line segment aux colouring is somewhat approximate. In most cases it is good enough for visual inspection, but pixel-level examination may reveal discrepancies. Usage Overview:  layerN=line3d colorN=<rrggbb>|red|blue|... thickN=<pixels> <pos-coord-paramsN> auxN=<num-expr> sortN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Positional Coordinate Parameters: The positional coordinates <pos-coord-paramsN> give a position for each row of the input table. Their form depends on the plot geometry, i.e. which plotting command is used. For a plane plot (plot2plane) the parameters would be xN and yN. The coordinate parameter values are in all cases strings interpreted as numeric expressions based on column names. These can be column names, fixed values or algebraic expressions as described in Section 10. Example:  stilts plot2cube in=iers.fits x=x y=y z=LOD layer1=line3d icmd1='select decYear>1963&&decYear<1964.5' thick1=3 aux1=LOD layer2=mark shading2=translucent color2=cccc00 translevel2=0.35 auxmap=cyan-magenta auxvisible=false legend=false phi=-150 theta=25 psi=180 xpix=400 ypix=400 auxN = <num-expr> (String) If supplied, this adjusts the colouring of the line along its length according to the value of this coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] sortN = <num-expr> (String) If supplied, this gives a value to define in what order points are joined together. If no value is given, the natural order is used, i.e. the sequence of rows in the table. Note that if the required order is in fact the natural order of the table, it is better to leave this value blank, since sorting is a potentially expensive step. The value is a numeric algebraic expression based on column names as described in Section 10. thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 1] #### 8.3.46 spheregrid Plots a spherical grid around the origin of a 3-d plot. The radius of the sphere can be configured explicitly, otherwise a suitable default value (that should make at least some of the grid visible) will be chosen. Usage Overview:  layerN=spheregrid radiusN=<number> gridcolorN=<rrggbb>|red|blue|... thickN=<pixels> nlonN=<int-value> nlatN=<int-value>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2sphere legend=false xpix=350 ypix=350 layer1=mark in1=tgas_source.fits lon1=ra lat1=dec r1=1 shading1=transparent opaque1=850 color1=orange layer2=spheregrid gridcolor2=green thick2=2  gridcolorN = <rrggbb>|red|blue|... (Color) The color of the spherical grid, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: grey] nlatN = <int-value> (Integer) Number of latitude lines to plot both above and below the equator in the spherical grid. A value of zero plots just the equator, and negative values plot no parallels at all. [Default: 2] nlonN = <int-value> (Integer) Number of longitude great circles to plot in the spherical grid. Since each great circle joins the poles in two hemispheres, this value is half the number of meridians to be drawn. [Default: 3] radiusN = <number> (Double) Defines the radius of the spherical grid that is drawn around the origin. Positive values give the radius in data units, negative values provide a multiplier for the default radius which is chosen on the basis of the currently visible volume. [Default: -1] thickN = <pixels> (Integer) Thickness of plotted line in pixels. [Default: 1] #### 8.3.47 yerror Plots symmetric or asymmetric error bars in the Y direction. Usage Overview:  layerN=yerror errorbarN=none|lines|capped_lines|caps|arrows thickN=<int-value> shadingN=flat <shade-paramsN> tN=<time-expr> ttypeN=DecYear|MJD|JD|Unix|Iso8601 yN=<num-expr> yerrhiN=<num-expr> yerrloN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2time in=ACE_data.vot t=epoch y=Bmag layer1=yerror yerrhi1=sigma_B errorbar1=capped_lines layer2=mark shape2=open_circle size2=3 layer3=line color3=a0a0a0 tmin=2001-08-17T07 tmax=2001-08-17T10 ypix=250 errorbarN = none|lines|capped_lines|caps|arrows (MultiPointShape) How errorbars are represented. The available options are: • none • lines • capped_lines • caps • arrows [Default: lines] icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] shadingN = flat <shade-paramsN> (ShapeMode) Determines how plotted objects in layer N are coloured. This may be influenced by how many objects are plotted over each other as well as the values of other parameters. Available options (Section 8.4) are: • flat Each of these options comes with its own set of parameters to specify the details of how colouring is done. [Default: flat] tN = <time-expr> (String) Time coordinate. The value is a Time value algebraic expression based on column names as described in Section 10. thickN = <int-value> (Integer) Controls the line thickness used when drawing shapes. Zero, the default value, means a 1-pixel-wide line is used. Larger values make drawn lines thicker, but note changing this value will not affect all shapes, for instance filled rectangles contain no line drawings. [Default: 0] ttypeN = DecYear|MJD|JD|Unix|Iso8601 (TimeMapper) Selects the form in which the Time value for parameter tN is supplied. Options are: • DecYear: Years since 0 AD • MJD: Modified Julian Date • JD: Julian Day • Unix: Seconds since midnight 1 Jan 1970 • Iso8601: ISO 8601 string If left blank, a guess will be taken depending on the data type of the value supplied for the tN value. yN = <num-expr> (String) Vertical coordinate. The value is a numeric algebraic expression based on column names as described in Section 10. yerrhiN = <num-expr> (String) Error in the Y coordinate in the positive direction. If no corresponding negative error value is supplied, then this value is also used in the negative direction, i.e. in that case errors are assumed to be symmetric. The value is a numeric algebraic expression based on column names as described in Section 10. yerrloN = <num-expr> (String) Error in the Y coordinate in the negative direction. If left blank, it is assumed to take the same value as the positive error. The value is a numeric algebraic expression based on column names as described in Section 10. #### 8.3.48 spectrogram Plots spectrograms. A spectrogram is a sequence of spectra plotted as vertical 1-d images, each one plotted at a different horizontal coordinate. This specialised layer is only available for time plots. The way that data values are mapped to colours is usually controlled by options at the level of the plot itself, rather than by per-layer configuration. Usage Overview:  layerN=spectrogram tN=<time-expr> ttypeN=DecYear|MJD|JD|Unix|Iso8601 spectrumN=<array-expr> twidthN=<num-expr> inN=<table> ifmtN=<in-format> istreamN=true|false icmdN=<cmds>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2time layer1=spectrogram in1=LRS_NPW_V010_20071101.cdf t1=epoch spectrum1=RX2 auxfunc=linear auxmap=plasma auxclip=0,1 xpix=600 ypix=300 tmin=2007-11-01T00 tmax=2007-11-01T12 ymax=500 icmdN = <cmds> (ProcessingStep[]) Specifies processing to be performed on the layer N input table as specified by parameter inN. The value of this parameter is one or more of the filter commands described in Section 6.1. If more than one is given, they must be separated by semicolon characters (";"). This parameter can be repeated multiple times on the same command line to build up a list of processing steps. The sequence of commands given in this way defines the processing pipeline which is performed on the table. Commands may alteratively be supplied in an external file, by using the indirection character '@'. Thus a value of "@filename" causes the file filename to be read for a list of filter commands to execute. The commands in the file may be separated by newline characters and/or semicolons, and lines which are blank or which start with a '#' character are ignored. ifmtN = <in-format> (String) Specifies the format of the input table as specified by parameter inN. The known formats are listed in Section 5.1.1. This flag can be used if you know what format your table is in. If it has the special value (auto) (the default), then an attempt will be made to detect the format of the table automatically. This cannot always be done correctly however, in which case the program will exit with an error explaining which formats were attempted. This parameter is ignored for scheme-specified tables. [Default: (auto)] inN = <table> (StarTable) The location of the input table. This may take one of the following forms: • A filename. • A URL. • The special value "-", meaning standard input. In this case the input format must be given explicitly using the ifmtN parameter. Note that not all formats can be streamed in this way. • A scheme specification of the form :<scheme-name>:<scheme-args>. • A system command line with either a "<" character at the start, or a "|" character at the end ("<syscmd" or "syscmd|"). This executes the given pipeline and reads from its standard output. This will probably only work on unix-like systems. In any case, compressed data in one of the supported compression formats (gzip, Unix compress or bzip2) will be decompressed transparently. istreamN = true|false (Boolean) If set true, the input table specified by the inN parameter will be read as a stream. It is necessary to give the ifmtN parameter in this case. Depending on the required operations and processing mode, this may cause the read to fail (sometimes it is necessary to read the table more than once). It is not normally necessary to set this flag; in most cases the data will be streamed automatically if that is the best thing to do. However it can sometimes result in less resource usage when processing large files in certain formats (such as VOTable). This parameter is ignored for scheme-specified tables. [Default: false] spectrumN = <array-expr> (String) Provides an array of spectral samples at each data point. The value must be a numeric array (e.g. the value of an array-valued column). The value is an array-valued algebraic expression based on column names as described in Section 10. Some of the functions in the Arrays class may be useful here. tN = <time-expr> (String) Time coordinate. The value is a Time value algebraic expression based on column names as described in Section 10. ttypeN = DecYear|MJD|JD|Unix|Iso8601 (TimeMapper) Selects the form in which the Time value for parameter tN is supplied. Options are: • DecYear: Years since 0 AD • MJD: Modified Julian Date • JD: Julian Day • Unix: Seconds since midnight 1 Jan 1970 • Iso8601: ISO 8601 string If left blank, a guess will be taken depending on the data type of the value supplied for the tN value. twidthN = <num-expr> (String) Range on the Time axis over which the spectrum is plotted. If no value is supplied, an attempt will be made to determine it automatically by looking at the spacing of the Time coordinates plotted in the spectrogram. The value is a numeric algebraic expression based on column names as described in Section 10. ### 8.4 Shading Modes Some plot layer types have an associated shading parameter which determines how plotted markers are coloured. This is independent of the marker shapes (which may be points, vectors, ellipses, ...) but may be affected by how many markers are plotted on top of each other, additional input table values, selected colour maps etc. For the simplest shading types (e.g. flat) it's just a case of choosing a colour, but the more complex ones have several associated parameters. The various shading types and their usages are described in the following subsections. #### 8.4.1 auto Paints isolated points in their selected colour but where multiple points in the same layer overlap it adjusts the clour by darkening it. This means that for isolated points (most or all points in a non-crowded plot, or outliers in a crowded plot) it behaves just like flat mode, but it's easy to see where overdense regions lie. This is like density mode, but with no user-configurable options. Usage:  shadingN=auto colorN=<rrggbb>|red|blue|...  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=mark in1=dr5qso.fits shading1=auto x1=psfmag_g-psfmag_r y1=psfmag_u-psfmag_g size1=2 xmin=-0.5 xmax=2.5 ymin=-1 ymax=6 Associated parameters are as follows: colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] #### 8.4.2 flat Paints markers in a single fixed colour. Usage:  shadingN=flat colorN=<rrggbb>|red|blue|...  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=mark in1=dr5qso.fits shading1=flat x1=psfmag_g-psfmag_r y1=psfmag_u-psfmag_g size1=2 xmin=-0.5 xmax=2.5 ymin=-1 ymax=6 Associated parameters are as follows: colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] #### 8.4.3 translucent Paints markers in a transparent version of their selected colour. The degree of transparency is determined by how many points are plotted on top of each other and by the transparency level. Unlike transparent mode, the transparency varies according to the average point density in the plot, so leaving the setting the same as you zoom in and out usually has a sensible effect. Usage:  shadingN=translucent colorN=<rrggbb>|red|blue|... translevelN=<number>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=mark in1=dr5qso.fits shading1=translucent x1=psfmag_g-psfmag_r y1=psfmag_u-psfmag_g size1=2 xmin=-0.5 xmax=2.5 ymin=-1 ymax=6 Associated parameters are as follows: colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] translevelN = <number> (Double) Sets the level of automatically controlled transparency. The higher this value the more transparent points are. Exactly how transparent points are depends on how many are currently being plotted on top of each other and the value of this parameter. The idea is that you can set it to some fixed value, and then get something which looks similarly transparent while you zoom in and out. [Default: 0.1] #### 8.4.4 transparent Paints markers in a transparent version of their selected colour. The degree of transparency is determined by how many points are plotted on top of each other and by the opaque limit. The opaque limit fixes how many points must be plotted on top of each other to completely obscure the background. This is set to a fixed value, so a transparent level that works well for a crowded region (or low magnification) may not work so well for a sparse region (or when zoomed in). Usage:  shadingN=transparent colorN=<rrggbb>|red|blue|... opaqueN=<number>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=mark in1=dr5qso.fits shading1=transparent x1=psfmag_g-psfmag_r y1=psfmag_u-psfmag_g size1=2 xmin=-0.5 xmax=2.5 ymin=-1 ymax=6 Associated parameters are as follows: colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] opaqueN = <number> (Double) The opacity of plotted points. The value is the number of points which have to be overplotted before the background is fully obscured. [Default: 4] #### 8.4.5 density Paints markers using a configurable colour map to indicate how many points are plotted over each other. Specifically, it colours each pixel according to how many times that pixel has has been covered by one of the markers plotted by the layer in question. To put it another way, it generates a false-colour density map with pixel granularity using a smoothing kernel of the form of the markers plotted by the layer. The upshot is that you can see the plot density of points or other markers plotted. This is like auto mode, but with more user-configurable options. Usage:  shadingN=density colorN=<rrggbb>|red|blue|... densemapN=<map-name>|<color>-<color>[-<color>...] denseclipN=<lo>,<hi> denseflipN=true|false densequantN=<number> densesubN=<lo>,<hi> densefuncN=log|linear|histogram|histolog|sqrt|square|acos|cos  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=mark in1=dr5qso.fits shading1=density densemap1=viridis x1=psfmag_g-psfmag_r y1=psfmag_u-psfmag_g size1=2 xmin=-0.5 xmax=2.5 ymin=-1 ymax=6 Associated parameters are as follows: colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] denseclipN = <lo>,<hi> (Subrange) Defines a subrange of the colour ramp to be used for Density shading. The value is specified as a (low,high) comma-separated pair of two numbers between 0 and 1. If the full range 0,1 is used, the whole range of colours specified by the selected shader will be used. But if for instance a value of 0,0.5 is given, only those colours at the left hand end of the ramp will be seen. If the null (default) value is chosen, a default clip will be used. This generally covers most or all of the range 0-1 but for colour maps which fade to white, a small proportion of the lower end may be excluded, to ensure that all the colours are visually distinguishable from a white background. This default is usually a good idea if the colour map is being used with something like a scatter plot, where markers are plotted against a white background. However, for something like a density map when the whole plotting area is tiled with colours from the map, it may be better to supply the whole range 0,1 explicitly. denseflipN = true|false (Boolean) If true, the colour map on the Density axis will be reversed. [Default: false] densefuncN = log|linear|histogram|histolog|sqrt|square|acos|cos (Scaling) Defines the way that values in the Density range are mapped to the selected colour ramp. The available options are: • log: Logarithmic scaling • linear: Linear scaling • histogram: Scaling follows data distribution, with linear axis • histolog: Scaling follows data distribution, with logarithmic axis • sqrt: Square root scaling • square: Square scaling • acos: Arccos Scaling • cos: Cos Scaling For all these options, the full range of data values is used, and displayed on the colour bar if applicable (though it can be restricted using the densesub option) The Linear, Log, Square and Sqrt options just apply the named function to the full data range. The histogram options on the other hand use a scaling function that corresponds to the actual distribution of the data, so that there are about the same number of points (or pixels, or whatever is being scaled) of each colour. The histogram options are somewhat more expensive, but can be a good choice if you are exploring data whose distribution is unknown or not well-behaved over its min-max range. The Histogram and HistoLog options both assign the colours in the same way, but they display the colour ramp with linear or logarithmic annotation respectively; the HistoLog option also ignores non-positive values. [Default: log] densemapN = <map-name>|<color>-<color>[-<color>...] (Shader) Color map used for Density axis shading. A mixed bag of colour ramps are available as listed in Section 8.7: blacker, whiter, inferno, magma, plasma, viridis, cividis, cubehelix, sron, rainbow, rainbow2, rainbow3, pastel, cosmic, ember, gothic, rainforest, voltage, bubblegum, gem, chroma, neon, tropical, accent, gnuplot, gnuplot2, specxby, set1, paired, hotcold, guppy, iceburn, redshift, pride, rdbu, piyg, brbg, cyan-magenta, red-blue, brg, heat, cold, light, greyscale, colour, standard, bugn, bupu, orrd, pubu, purd, painbow, huecl, infinity, hue, intensity, rgb_red, rgb_green, rgb_blue, hsv_h, hsv_s, hsv_v, yuv_y, yuv_u, yuv_v, scale_hsv_s, scale_hsv_v, scale_yuv_y. Note: many of these, including rainbow-like ones, are frowned upon by the visualisation community. You can also construct your own custom colour map by giving a sequence of colour names separated by minus sign ("-") characters. In this case the ramp is a linear interpolation between each pair of colours named, using the same syntax as when specifying a colour value. So for instance "yellow-hotpink-#0000ff" would shade from yellow via hot pink to blue. [Default: blacker] densequantN = <number> (Double) Allows the colour map used for the Density axis to be quantised. If an integer value N is chosen then the colour map will be viewed as N discrete evenly-spaced levels, so that only N different colours will appear in the plot. This can be used to generate a contour-like effect, and may make it easier to trace the boundaries of regions of interest by eye. If left blank, the colour map is nominally continuous (though in practice it may be quantised to a medium-sized number like 256). densesubN = <lo>,<hi> (Subrange) Defines a normalised adjustment to the data range of the Density axis. The value may be specified as a comma-separated pair of two numbers, giving the lower and upper bounds of the range of of interest respectively. This sub-range is applied to the data range that would otherwise be used, either automatically calculated or explicitly supplied; zero corresponds to the lower bound and one to the upper. The default value "0,1" therefore has no effect. The range could be restricted to its lower half with the value 0,0.5. [Default: 0,1] #### 8.4.6 aux Paints markers in a colour determined by the value of an additional data coordinate. The marker colours then represent an additional dimension of the plot. You can also adjust the transparency of the colours used. The way that data values are mapped to colours is usually controlled by options at the level of the plot itself, rather than by per-layer configuration. Usage:  shadingN=aux auxN=<num-expr> auxnullcolorN=<rrggbb>|red|blue|... opaqueN=<number>  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=mark in1=dr5qso.fits shading1=aux aux1=z auxmap=plasma x1=psfmag_g-psfmag_r y1=psfmag_u-psfmag_g size1=2 xmin=-0.5 xmax=2.5 ymin=-1 ymax=6 Associated parameters are as follows: auxN = <num-expr> (String) Colour coordinate for Aux shading. This parameter gives a column name, fixed value, or algebraic expression for the aux coordinate for layer N. The value is a numeric algebraic expression based on column names as described in Section 10. auxnullcolorN = <rrggbb>|red|blue|... (Color) The color of points with a null value of the Aux coordinate, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. If the value is null, then points with a null Aux value will not be plotted at all. [Default: grey] opaqueN = <number> (Double) The opacity of points plotted in the Aux colour. The value is the number of points which have to be overplotted before the background is fully obscured. [Default: 1] #### 8.4.7 weighted Paints markers like the Density mode, but with optional weighting by an additional coordinate. You can configure how the weighted coordinates are combined to give the final weighted result. The way that data values are mapped to colours is usually controlled by options at the level of the plot itself, rather than by per-layer configuration. Usage:  shadingN=weighted weightN=<num-expr> colorN=<rrggbb>|red|blue|... combineN=sum|count|mean|median|q1|q3|min|max|stdev|hit  All the parameters listed here affect only the relevant layer, identified by the suffix N. Example:  stilts plot2plane layer1=mark in1=dr5qso.fits shading1=weighted weight1=z auxmap=plasma x1=psfmag_g-psfmag_r y1=psfmag_u-psfmag_g size1=2 xmin=-0.5 xmax=2.5 ymin=-1 ymax=6 Associated parameters are as follows: colorN = <rrggbb>|red|blue|... (Color) The color of plotted data, given by name or as a hexadecimal RGB value. The standard plotting colour names are red, blue, green, grey, magenta, cyan, orange, pink, yellow, black, light_grey, white. However, many other common colour names (too many to list here) are also understood. The list currently contains those colour names understood by most web browsers, from AliceBlue to YellowGreen, listed e.g. in the Extended color keywords section of the CSS3 standard. Alternatively, a six-digit hexadecimal number RRGGBB may be supplied, optionally prefixed by "#" or "0x", giving red, green and blue intensities, e.g. "ff00ff", "#ff00ff" or "0xff00ff" for magenta. [Default: red] combineN = sum|count|mean|median|q1|q3|min|max|stdev|hit (Combiner) Defines how values contributing to the same pixel are combined together to produce the value assigned to that pixel (and hence its colour). When a weight is in use, mean or sum are typically sensible choices. If there is no weight (a pure density map) then count is usually better, but in that case it may make more sense (it is more efficient) to use one of the other shading modes instead. The available options are: • sum: the sum of all the combined values per bin • count: the number of non-blank values per bin (weight is ignored) • mean: the mean of the combined values • median: the median • q1: first quartile • q3: third quartile • min: the minimum of all the combined values • max: the maximum of all the combined values • stdev: the sample standard deviation of the combined values • hit: 1 if any values present, NaN otherwise (weight is ignored) [Default: mean] weightN = <num-expr> (String) Weight coordinate for weighted density shading. This parameter gives a column name, fixed value, or algebraic expression for the weight coordinate for layer N. The value is a numeric algebraic expression based on column names as described in Section 10. ### 8.5 Output Modes The plots generated by the plotting commands can be used in various different ways. One thing you might want to do is to write the output to a file in a given graphics format (out); another is to preview it directly on the screen (swing). By default one or other of these will happen depending on whether you specify an output file. However there are other possibilities; these are listed in the following subsections. Except for display to the screen, these modes should work happily on a headless machine (one with no graphics display, as may be the case for a web server). When running headless, you may find it necessary to set the java system property "java.awt.headless" to true - see Section 3.3. The default output mode is auto, which means that output is to a file if an output file is specified, or to the screen if it is not. So in most cases you don't need to specify the omode parameter explicitly. #### 8.5.1 swing Usage: omode=swing Plot will be displayed in a window on the screen. This plot is "live"; it can be resized and (except for old-style plots) navigated around with mouse actions in the same way as plots in TOPCAT. #### 8.5.2 out Usage: omode=out out=<out-file> ofmt=png|png-transp|gif|jpeg|pdf|svg|eps|eps-gzip Plot will be written to a file given by out using the graphics format given by ofmt. #### 8.5.3 cgi Usage: omode=cgi ofmt=png|png-transp|gif|jpeg|pdf|svg|eps|eps-gzip Plot will be written in a way suitable for CGI use direct from a web server. The output is in the graphics format given by ofmt, preceded by a suitable "Content-type" declaration. #### 8.5.4 discard Usage: omode=discard Plot is drawn, but discarded. There is no output. #### 8.5.5 auto Usage: omode=auto [out=<out-file>] Behaves as swing or out mode depending on presence of out parameter ### 8.6 Export Formats Several of the plot output modes write the plot in some graphics format or other. When selecting an output format it is important to understand the distinction between bitmapped and vector formats; basically bitmapped formats represent the image as a grid of finite-sized pixels while vector formats notionally draw smooth lines. Bitmapped formats are fine for a computer screen, but for high quality paper printouts you will want a vector format. You can convert from vector to bitmapped but not (usefully) in the other direction. There are a couple of subtleties to this distinction specific to STILTS graphical output as discussed below. The following formats are the available values for the ofmt parameter of the various plot commands: png PNG format. This is a flexible bitmapped format providing transparency and an unlimited number of colours with good lossless compression. It is widely supported by non-ancient browsers and other image viewers, and is generally recommended for bitmapped output. gif GIF format. This is a bitmapped format providing transparency and lossless compression. The number of colours is limited to 255 however, so if you are using auxiliary axes (colour variation to represent higher dimensionality) or other plot features which use a wide range of colours you may see image degradation. It has long been widely supported by browsers and other image viewers. jpeg JPEG format. This is a bitmapped format with lossy compression intended primarily for photographs. Transparency is not supported, and although there is no limit on the maximum number of colours, its lossiness means that plots generated using it generally look a bit smudged. pdf Portable Document Format. This is the format which can be read by Adobe's Acrobat Reader. It is a widely portable vector format, and is suitable for printing at high resolution, either standalone or imported into some other presentation format. However, there are a couple of caveats when it comes to using it with STILTS plots. 1. If used to plot a very large number of points, the output PDF file can get quite large, though it's much better than for eps output (see below). 2. For certain colour shading options (auto, density, and in some circumstances transparency), the body of the plot will be drawn as a bitmap rather than vector graphics. This is sometimes a blessing in disguise since with very large numbers of points a vector PDF file could get unmanageably large in any case. In this case the interior of the plot will be pixellated. The axes and annotations outside of the plot will still be drawn in vector format however. svg Scalable Vector Graphics. This is an XML-based vector graphics format developed for display in web pages, and defined by the W3C. This exporter can generate OutOfMemoryErrors if asked to generate a large output file. eps Encapsulated Postscript. This is a vector format which is suitable for printing at high resolution either standalone or imported into some other presentation format (you may need to convert it via PDF depending on the intended destination). However, there are a couple of caveats when it comes to using it with STILTS plots. 1. Unfortunately the postscript driver used by STILTS is not very efficient and can result in large, sometimes very large, postscript output files. This is likely to be a problem for plots with a large number of non-transparent points. For this reason eps-gzip or pdf may be a better choice. 2. Postscript has no support for partial transparency, so if plots are drawn with partially transparent points (common for very large data sets) the only way they can be rendered is by drawing the body of the plot as a bitmap rather than as vector graphics. This is sometimes a blessing in disguise since with very large numbers of points a vector postscript file would likely be unmanageably large in any case. So if there is any transparency in the plot, the interior of the plot will be pixellated. The axes and annotations outside of the plot will still be drawn in vector format however. eps-gzip Just like the eps format above except that the output is automatically compressed using the GZIP format as it is written. Postscript compresses well (typically a factor of 5-10). ### 8.7 Colour Maps A number of colour maps are available, and used for instance with the shading modes density, aux and weighted. Not all colour maps are suitable/available in all contexts, and in some cases the maps are by default clipped at one end to avoid for instance white-on-white plotting, but the lists below give an overview of which named colourmaps can be used. Note that custom colourmaps can also be used by supplying a specification like "red-yellow-blue". The absolute colour maps are listed below: these do not depend on the underlying colour of the plotted symbols, so are suitable when only one dataset is being plotted. Absolute colour maps The non-absolute colour maps are listed below: these modify an underlying colour, so are suitable for applying to several different datasets with different underlying colours. The representation here shows how they affect several different colours; for each row of pixels the unmodified (value=0) colour is at the left of the image and the most modified (value=1) is at the right. Non-absolute colour maps These colour maps have been derived from several sources, including SkyCat/GAIA, MatPlotLib 1.5, Gnuplot, Daniel Michalik, Paul Tol, CMasher, Color Brewer, HCL Wizard, Dave Green, xkcd, and maybe some others I forgot. ## 9 Old-Style Plotting This section describes deprecated commands. For recommended plotting commands, see Section 8. From version 2.0 (October 2008), STILTS incorporated three table plotting commands: These provided command-line access to some, though not all, of the plotting capabilities offered by TOPCAT. Since version 3.0 (October 2014), these commands are deprecated in favour of the more powerful ones described in Section 8. The rest of this section describes some aspects of the deprecated commands for the benefit of legacy code. The output modes and formats are the same in old- and new-style plots, and are discussed in Section 8.5 and Section 8.6. The handling of parameters and suffixes for these commands is not quite the same as for new-style plots, and is documented in the next subsection. As a simple example, if a file "cat.fits" contains the columns RMAG and BMAG for red and blue magnitudes, you can draw a two-dimensional colour-magnitude scatter plot with the command:  stilts plot2d in=cat.fits xdata=BMAG-RMAG ydata=BMAG  Since an output file is not specified, the plot is shown on the screen for convenience. To send the output to a PNG file, do instead:  stilts plot2d in=cat.fits xdata=BMAG-RMAG ydata=BMAG out=plot.png ofmt=png  in some cases (including the above), the ofmt parameter is not required since STILTS may be able to guess the format from the output file name. Various other options for output and graphics formats are described in Section 8.5 and Section 8.6 Some of the parameters use suffixes to define data sets and therefore behave a bit differently from the parameters elsewhere in STILTS - a discussion of these is given in the following subsection. Some other plotting-specific topics are also discussed below. ### 9.1 Parameter Suffixes This section describes deprecated commands. For recommended plotting commands, see Section 8. Some of the parameters for the plotting tasks behave a little bit differently to other parameters in STILTS, in order to accommodate related sets of values. If you look at the usage of one of the plotting commands, for instance in Appendix B.15.1, you will see that a number of the parameters have the suffixes "N" or "NS". These suffixes can be substituted with any convenient string to identify parameters which relate to the same input datasets or subsets. Specifically: Suffix "N": Denotes an input dataset. At least the inN parameter must be given to identify the source of the data; any other parameters with the same value of the N suffix relate to that dataset. A dataset here refers to a particular set of plot data from a table; in most cases each input table corresponds to a different dataset, though two datasets may correspond to different sets of columns from the same table. Suffix "NS": Denotes a particular subset of the rows in dataset N. At least the subsetNS parameter must be given to identify the expression by which the subset is defined; any other parameters with the same value of the NS suffix relate to that subset. Some examples will help to illustrate. The following will generate a Cartesian plot of catalogue position from a single dataset:  stilts plot2d in=gals.fits xdata=RA ydata=DEC  In this case the N suffix is present on each of the parameters in, xdata and ydata, but is equal to the empty string, hence invisible. This is perfectly legal, and convenient when only a single table is in use. If we wish to overplot two datasets however, the dataset suffixes (or one of them at least) have to be made explicit so that different ones can be used, for instance:  stilts plot2d in1=gals.fits xdata1=RA ydata1=DEC in2=stars.fits xdata2=RAJ2000 ydata2=DEJ2000  The suffix values "1" and "2" are quite arbitrary and can be chosen as convenient, so the following would do exactly the same as the previous example:  stilts plot2d in_GAL=gals.fits xdata_GAL=RA ydata_GAL=DEC in_STAR=stars.fits xdata_STAR=RAJ2000 ydata_STAR=DEJ2000  The other parameters which have the N suffix apply only to the matching dataset, so for instance the following:  stilts plot2d in1=gals.fits xdata1=RA ydata1=DEC txtlabel1=NGC_ID in2=stars.fits xdata2=RAJ2000 ydata2=DEJ2000  would draw text labels adjacent to the points from only the gals.fits file giving the contents of its NGC_ID column. The NS suffix identifies distinct row subsets within the same or different datasets. A subset is defined by supplying a boolean inclusion expression (each row is included only if the expression evaluates true for that row) as the value of a subsetNS parameter. If, as in all the examples we have seen so far, no subsetNS parameter is supplied for a given dataset, then it is treated as a special case, as if a single subset with a name equal to the empty string (S="") containing all rows has been specified. So our earlier simple example:  stilts plot2d in=gals.fits xdata=RA ydata=DEC  is equivalent to  stilts plot2d in=gals.fits xdata=RA ydata=DEC subset=true  If we wish to split the plotted points into two sets based on their R-B colours, we can write something like:  stilts plot2d in=gals.fits xdata=RA ydata=DEC subsetX='RMAG-BMAG>0' subsetY='RMAG-BMAG<=0'  This will generate a plot with two subsets shown using different colours and/or plotting symbols. These colours and symbols are selected automatically. More control over the appearance can be exercised by setting values for some of the other parameters with NS suffixes, for instance  stilts plot2d in=gals.fits xdata=RA ydata=DEC subset_A='RMAG-BMAG>0' colour_A=blue subset_B='RMAG-BMAG<=0' colour_B=red  Again, the suffix strings can be chosen to have any value as convenient. The dataset- and subset-specific parameters must be put together if there are multiple datasets with multiple subsets to plot simultaneously, for instance:  stilts plot2d in_1=gals.fits xdata_1=RA ydata_1=DEC subset_1_A='RMAG-BMAG>0' colour_1_A=blue subset_1_B='RMAG-BMAG<=0' colour_1_B=red in_2=stars.fits xdata_2=RAJ2000 ydata_2=DEJ2000 colour_2=green  Finally, it's not quite true that the suffixes chosen have no effect on the plot; they may influence the order in which sets are plotted. Markers drawn for sets plotted earlier may be obscured by the markers drawn for sets plotted later, so this can affect the appearance of the plot. If you want to control this, use the sequence parameter. For instance, to ensure that star data appears on top of galaxy data in the plot, do the following:  stilts plot2d in_GAL=gals.fits xdata_GAL=RA ydata_GAL=DEC in_STAR=stars.fits xdata_STAR=RAJ2000 ydata_STAR=DEJ2000 sequence=_GAL,_STAR  More examples can be found in the Examples subsections of the individual plotting command descriptions in Appendix B. ## 10 Algebraic Expression Syntax Many of the STILTS commands allow you to use algebraic expressions based on table columns when doing things like making row selections, defining new columns, selecting values to plot or match, and so on. In these cases you are defining an expression which has a value in each row as a function of the values in the existing columns in that row. This is a powerful feature which permits you to manipulate and select table data in very flexible ways. The syntax for entering these expressions is explained in this section. What you write are actually expressions in the Java language, which are compiled into Java bytecode before evaluation. However, this does not mean that you need to be a Java programmer to write them. The syntax is pretty similar to C, but even if you've never programmed in C most simple things, and many complicated ones, are quite intutitive. The following explanation gives some guidance and examples for writing these expressions. Unfortunately a complete tutorial on writing Java expressions is beyond the scope of this document, but it should provide enough information for even a novice to write useful expressions. The expressions that you can write are basically any function of all the column values which apply to a given row; the function result can then be used where STILTS needs a per-row value, for instance to define a new column. If the built-in operators and functions are not sufficient, or it's unwieldy to express your function in one line of code, it is possible to add new functions by writing your own classes - see Section 10.8.3. Note that since these algebraic expressions often contain spaces, you may need to enclose them in single or double quotes so that they don't get confused with other parts of the command string. Note: if Java is running in an environment with certain security restrictions (a security manager which does not permit creation of custom class loaders) then algebraic expressions won't work at all. It's not particularly likely that security restrictions will be in place if you are running from the command line though. ### 10.1 Referencing Column Values To create a useful expression which can be evaluated for each row in a table, you will have to refer to cells in different columns of that row. You can do this in several ways: By Name The Name of the column may be used if it is unique (no other column in the table has the same name) and if it has a suitable form. This means that it must have the form of a Java variable - basically starting with a letter and continuing with letters, numbers, underscores and currency symbols. In particular it cannot contain spaces, commas, parentheses etc. As a special case, if an expression contains just a single column name, rather than some more complicated expression, then any column name may be used, even one containing non-alphanumeric characters. Column names are treated case-insensitively. ByID
The "$ID" identifier of the column may always be used to refer to it; this is a useful fallback if the column name isn't suitable for some reason (for instance it contains spaces or is not unique). This is just a "$" sign followed by the column index - the first column is $1. By ucd$ specifier
If the column has a Unified Content Descriptor (this will usually only be the case for VOTable or possibly FITS format tables) you can refer to it using an identifier of the form "ucd$<ucd-spec>". Depending on the version of UCD scheme used, UCDs can contain various punctuation marks such as underscores, semicolons and dots; for the purpose of this syntax these should all be represented as underscores ("_"). So to identify a column which has the UCD "phot.mag;em.opt.R", you should use the identifier "ucd$phot_mag_em_opt_r". Matching is not case-sensitive. Futhermore, a trailing underscore acts as a wildcard, so that the above column could also be referenced using the identifier "ucd$phot_mag_". If multiple columns have UCDs which match the given identifer, the first one will be used. Note that the same syntax can be used for referencing table parameters (see the next section); columns take preference so if a column and a parameter both match the requested UCD, the column value will be used. By utype$ specifier
If the column has a Utype (this will usually only be the case for VOTable or possibly FITS format tables) you can refer to it using an identifier of the form "utype$<utype-spec>". Utypes can contain various punctuation marks such as colons and dots; for the purpose of this syntax these should all be represented as underscores ("_"). So to identify a column which has the Utype "ssa:Access.Format", you should use the identifier "utype$ssa_Access_Format". Matching is not case-sensitive. If multiple columns have Utypes which match the given identifier, the first one will be used.

Note that the same syntax can be used for referencing table parameters (see the next section); columns take preference so if a column and a parameter both match the requested Utype, the column value will be used.

Using value*() functions
You can use the special functions valueDouble, valueInt, valueLong, valueString and valueObject to obtain the typed value of a column with a given name. The argument of the function is a string giving the exact (case-sensitive) column name, for instance valueDouble("b_E(BP-RP)") will yield the value of the column named "b_E(BP-RP)" as a double-precision floating point value. These functions are not the generally recommended way to get column values, since they are slower and provide less type-checking than the other options listed above, and can occasionally lead to some other esoteric problems. However, if you need to refer by name to strangely-named columns they are sometimes a convenient option.
With the Object$prefix If a column is referenced with the prefix "Object$" before its identifier (e.g. "Object$BMAG" for a column named BMAG) the result will be the column value as a java Object. Without that prefix, numeric columns are evaluated as java primitives. In most cases, you don't want to do this, since it means that you can't use the value in arithmetic expressions. However, if you need the value to be passed to a (possibly user-defined) method, and you need that method to be invoked even when the value is null, you have to do it like this. Null-valued primitives otherwise cause expression evaluation to abort. The value of the variables so referenced will be a primitive (boolean, byte, short, char, int, long, float, double) if the column contains one of the corresponding types. Otherwise it will be an Object of the type held by the column, for instance a String. In practice this means: you can write the name of a column, and it will evaluate to the numeric (or string) value that that column contains in each row. You can then use this in normal algebraic expressions such as "B_MAG-U_MAG" as you'd expect. ### 10.2 Referencing Parameter Values Some tables have constant values associated with them; these may represent such things as the epoch at which observations were taken, the name of the catalogue, an angular resolution associated with all observations, or any number of other things. Such constants are known as table parameters (not to be confused with parameters passed to STILTS commands) and can be thought of as extra columns which have the same value for every row. The values of such parameters can be referenced in STILTS algebraic expressions as follows: param$name
If the parameter name has a suitable form (starting with a letter and continuing with letters or numbers) it can be referenced by prefixing that name with the string param$. ucd$ucd-spec
If the parameter has a Unified Content Descriptor it can be referenced by prefixing the UCD specifier with the string ucd$. Any punctuation marks in the UCD should be replaced by underscores, and a trailing underscore is interpreted as a wildcard. See Section 10.1 for more discussion. utype$utype-spec
If the parameter has a Utype, it can be referenced by prefixing the Utype specifier with the string utype$. Any punctuation marks in the Utype should be replaced by underscores. See Section 10.1 for more discussion. Note that if a parameter has a name in an unsuitable form (e.g. containing spaces) and has no UCD then it cannot be referenced in an expression. One possible workaround for that is to use the fixcolnames filter. ### 10.3 Special Tokens There are a few pseudo-variables which have special functions in the expression language. The following specials are column-like, in that they have a different value for each row:$index or $0 The value of this is the current row number (the first row is 1). Note that this value is a long (8-byte integer); when using it in certain expressions you may find it necessary to convert it to an int (4-byte integer) using the toInteger() function. The deprecated alias "INDEX" may also be used.$random (Deprecated)
Evaluates to a double-precision random number 0<=x<1. NOTE: this token is deprecated since it can behave unpredictably (the same cell does not always yield the same result). Use instead the random() function in class Maths.

The following specials are parameter-like, in that their value is not sensitive to the row:

$ncol The number of columns in the table.$nrow
The number of rows in the table. Note in some cases this is not known (e.g. if the table is being streamed), in which case the value of this variable is null. Note also that this value is a long (8-byte integer); when using it in certain expressions you may find it necessary to convert it to an int (4-byte integer) using the toInteger() function.

### 10.4 Null Values

When no special steps are taken, if a null value (blank cell) is encountered in evaluating an expression (usually because one of the columns it relies on has a null value in the row in question) then the result of the expression is also null.

It is possible to exercise more control than this, but it requires a little bit of care, because the expressions work in terms of primitive values (numeric or boolean ones) which don't in general have a defined null value. The name "null" in expressions gives you the java null reference, but this cannot be matched against a primitive value or used as the return value of a primitive expression.

For most purposes, the following two tips should enable you to work with null values:

Testing for null
To test whether a column contains a null value, prepend the string "NULL_" (use upper case) to the column name or \$ID. This will yield a boolean value which is true if the column contains a blank, and false otherwise.
Returning null
To return a null value from a numeric expression, use the name "NULL" (upper case). To return a null value from a non-numeric expression (e.g. a String column) use the name "null" (lower case).

Null values are often used in conjunction with the conditional operator, "? :"; the expression

   test ? tval : fval

returns the value tval if the boolean expression test evaluates true, or fval if test evaluates false. So for instance the following expression:
   Vmag == -99 ? NULL : Vmag

can be used to define a new column which has the same value as the Vmag column for most values, but if Vmag has the "magic" value -99 the new column will contain a blank. The opposite trick (substituting a blank value with a magic one) can be done like this:
   NULL_Vmag ? -99 : Vmag

Some more examples are given in Section 10.7.

Note that for floating point data, STILTS treats null and NaN (Not-a-Number) values somewhat interchangeably. Blank values arising either from an input file format that can represent missing values, or from processing that fails to provide a definite value, are in most cases represented internally as null for integer-type values and NaN for floating point values. However in general users should not rely on distinguishing between null and NaN.

### 10.5 Operators

The operators are pretty much the same as in the C language. The common ones are:

Arithmetic
+ (add)
- (subtract)
* (multiply)
/ (divide)
% (modulus)
Boolean
! (not)
&& (and)
|| (or)
^ (exclusive-or)
== (numeric identity)
!= (numeric non-identity)
< (less than)
> (greater than)
<= (less than or equal)
>= (greater than or equal)
Bitwise
& (and)
| (or)
^ (exclusive-or)
<< (left shift)
>> (right shift)
>>> (logical right shift)
Numeric Typecasts
(byte) (numeric -> signed byte)
(short) (numeric -> 2-byte integer)
(int) (numeric -> 4-byte integer)
(long) (numeric -> 8-byte integer)
(float) (numeric -> 4-type floating point)
(double) (numeric -> 8-byte floating point)
Note you may find the Maths conversion functions more convenient for numeric conversions than these.
Other
+ (string concatenation)
[] (array dereferencing - first element is zero)
?: (conditional switch)
instanceof (class membership)

### 10.6 Functions

Many functions are available for use within your expressions, covering standard mathematical and trigonometric functions, arithmetic utility functions, type conversions, and some more specialised astronomical ones. You can use them in just the way you'd expect, by using the function name (unlike column names, this is case-sensitive) followed by comma-separated arguments in brackets, so

    max(IMAG,JMAG)

will give you the larger of the values in the columns IMAG and JMAG, and so on.

The functions available for use by default are listed by class in the following subsections with their arguments and short descriptions. The funcs command provides another way to browse these function descriptions online.

#### 10.6.1 Arithmetic

Standard arithmetic functions including things like rounding, sign manipulation, and maximum/minimum functions. Phase folding operations, and a convenient form of the modulus operation on which they are based, are also provided.

roundUp( x )
Rounds a value up to an integer value. Formally, returns the smallest (closest to negative infinity) integer value that is not less than the argument.

• Parameters:
• x (floating point): a value.
• Return value
• (integer): x rounded up

roundDown( x )
Rounds a value down to an integer value. Formally, returns the largest (closest to positive infinity) integer value that is not greater than the argument.

• Parameters:
• x (floating point): a value
• Return value
• (integer): x rounded down

round( x )
Rounds a value to the nearest integer. Formally, returns the integer that is closest in value to the argument. If two integers are equally close, the result is the even one.

• Parameters:
• x (floating point): a floating point value.
• Return value
• (integer): x rounded to the nearest integer

roundDecimal( x, dp )
Rounds a value to a given number of decimal places. The result is a float (32-bit floating point value), so this is only suitable for relatively low-precision values. It's intended for truncating the number of apparent significant figures represented by a value which you know has been obtained by combining other values of limited precision. For more control, see the functions in the Formats class.

• Parameters:
• x (floating point): a floating point value
• dp (integer): number of decimal places (digits after the decimal point) to retain
• Return value
• (floating point): floating point value close to x but with a limited apparent precision
• Example:
• roundDecimal(PI,2) = 3.14f

abs( x )
Returns the absolute value of an integer value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned.

• Parameters:
• x (integer): the argument whose absolute value is to be determined
• Return value
• (integer): the absolute value of the argument.

abs( x )
Returns the absolute value of a floating point value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned.

• Parameters:
• x (floating point): the argument whose absolute value is to be determined
• Return value
• (floating point): the absolute value of the argument.

max( a, b )
Returns the greater of two integer values. If the arguments have the same value, the result is that same value.

Multiple-argument maximum functions are also provided in the Arrays and Lists packages.

• Parameters:
• a (integer): an argument.
• b (integer): another argument.
• Return value
• (integer): the larger of a and b.

maxNaN( a, b )
Returns the greater of two floating point values. If the arguments have the same value, the result is that same value. If either value is blank, then the result is blank.

• Parameters:
• a (floating point): an argument.
• b (floating point): another argument.
• Return value
• (floating point): the larger of a and b.

maxReal( a, b )
Returns the greater of two floating point values, ignoring blanks. If the arguments have the same value, the result is that same value. If one argument is blank, the result is the other one. If both arguments are blank, the result is blank.

Multiple-argument maximum functions are also provided in the Arrays and Lists packages.

• Parameters:
• a (floating point): an argument
• b (floating point): another argument
• Return value
• (floating point): the larger non-blank value of a and b

min( a, b )
Returns the smaller of two integer values. If the arguments have the same value, the result is that same value.

Multiple-argument minimum functions are also provided in the Arrays and Lists packages.

• Parameters:
• a (integer): an argument.
• b (integer): another argument.
• Return value
• (integer): the smaller of a and b.

minNaN( a, b )
Returns the smaller of two floating point values. If the arguments have the same value, the result is that same value. If either value is blank, then the result is blank.

• Parameters:
• a (floating point): an argument.
• b (floating point): another argument.
• Return value
• (floating point): the smaller of a and b.

minReal( a, b )
Returns the smaller of two floating point values, ignoring blanks. If the arguments have the same value, the result is that same value. If one argument is blank, the result is the other one. If both arguments are blank, the result is blank.

Multiple-argument minimum functions are also provided in the Arrays and Lists packages.

• Parameters:
• a (floating point): an argument
• b (floating point): another argument
• Return value
• (floating point): the larger non-blank value of a and b

mod( a, b )
Returns the non-negative remainder of a/b. This is a modulo operation, but differs from the expression a%b in that the answer is always >=0 (as long as b is not zero).

• Parameters:
• a (floating point): dividend
• b (floating point): divisor
• Return value
• (floating point): non-negative remainder when dividing a by b
• Examples:
• modulo(14, 5) = 4
• modulo(-14, 5) = 1
• modulo(2.75, 0.5) = 0.25

phase( t, period )
Returns the phase of a value within a period.

For positive period, the returned value is in the range [0,1).

• Parameters:
• t (floating point): value
• period (floating point): folding period
• Return value
• (floating point): mod(t,period)/period
• Examples:
• phase(7, 4) = 0.75
• phase(-1000.5, 2.5) = 0.8
• phase(-3300, 33) = 0

phase( t, period, t0 )
Returns the phase of an offset value within a period. The reference value t0 corresponds to phase zero.

For positive period, the returned value is in the range [0,1).

• Parameters:
• t (floating point): value
• period (floating point): folding period
• t0 (floating point): reference value, corresponding to phase zero
• Return value
• (floating point): phase(t-t0, period)
• Examples:
• phase(5003,100,0) = 0.03
• phase(5003,100,2) = 0.01
• phase(5003,100,4) = 0.99

phase( t, period, t0, phase0 )
Returns the offset phase of an offset value within a period. The reference value t0 corresponds to integer phase value, and the phase offset phase0 determines the starting value for the phase range.

For positive period, the returned value is in the range [phase0,phase0+1).

• Parameters:
• t (floating point): value
• period (floating point): folding period
• t0 (floating point): reference value, corresponding to phase zero
• phase0 (floating point): offset for phase
• Return value
• (floating point): offset phase
• Examples:
• phase(23,10,1,99) = 99.2
• phase(8.6125,0.2,0.0125,-0.3) = 0
• phase(8.6125,0.2,0.1125,-0.7) = -0.5

#### 10.6.2 Arrays

Functions which operate on array-valued cells. The array parameters of these functions can only be used on values which are already arrays (usually, numeric arrays). In most cases that means on values in table columns which are declared as array-valued. FITS and VOTable tables can have columns which contain array values, but other formats such as CSV cannot.

If you want to calculate aggregating functions like sum, min, max etc on multiple values which are not part of an array, it's easier to use the functions from the Lists class.

Note that none of these functions will calculate statistical functions over a whole column of a table.

The functions fall into a number of categories:

• Aggregating operations, which map an array value to a scalar, including size, count, countTrue, maximum, minimum, sum, mean, median, quantile, stdev, variance, join.
• Operations on one or more arrays which produce array results, including add, subtract, multiply, divide, reciprocal, condition, slice, pick. Mostly these work on any numeric array type and return floating point (double precision) values, but some of them (slice, pick) have variants for different array types.
• The function array, which lets you assemble a floating point array value from a list of scalar numbers. There are variants (intArray, stringArray) for some different array types.

sum( array )
Returns the sum of all the non-blank elements in the array. If array is not a numeric array, null is returned.

• Parameters:
• array (Object): array of numbers
• Return value
• (floating point): sum of all the numeric values in array

mean( array )
Returns the mean of all the non-blank elements in the array. If array is not a numeric array, null is returned.

• Parameters:
• array (Object): array of numbers
• Return value
• (floating point): mean of all the numeric values in array

variance( array )
Returns the population variance of all the non-blank elements in the array. If array is not a numeric array, null is returned.

• Parameters:
• array (Object): array of numbers
• Return value
• (floating point): variance of the numeric values in array

stdev( array )
Returns the population standard deviation of all the non-blank elements in the array. If array is not a numeric array, null is returned.

• Parameters:
• array (Object): array of numbers
• Return value
• (floating point): standard deviation of the numeric values in array

minimum( array )
Returns the smallest of the non-blank elements in the array. If array is not a numeric array, null is returned.

• Parameters:
• array (Object): array of numbers
• Return value
• (floating point): minimum of the numeric values in array

maximum( array )
Returns the largest of the non-blank elements in the array. If array is not a numeric array, null is returned.

• Parameters:
• array (Object): array of numbers
• Return value
• (floating point): maximum of the numeric values in array

median( array )
Returns the median of the non-blank elements in the array. If array is not a numeric array, null is returned.

• Parameters:
• array (Object): array of numbers
• Return value
• (floating point): median of the numeric values in array

quantile( array, quant )
Returns a quantile value of the non-blank elements in the array. Which quantile is determined by the quant value; values of 0, 0.5 and 1 give the minimum, median and maximum respectively. A value of 0.99 would give the 99th percentile.

• Parameters:
• array (Object): array of numbers
• quant (floating point): number in the range 0-1 deterining which quantile to calculate
• Return value
• (floating point): quantile corresponding to quant

size( array )
Returns the number of elements in the array. If array is not an array, zero is returned.

• Parameters:
• array (Object): array
• Return value
• (integer): size of array

count( array )
Returns the number of non-blank elements in the array. If array is not an array, zero is returned.

• Parameters:
• array (Object): array (may or may not be numeric)
• Return value
• (integer): number of non-blank elements in array

countTrue( array )
Returns the number of true elements in an array of boolean values.

• Parameters:
• array (array of boolean): array of true/false values
• Return value
• (integer): number of true values in array

join( array, joiner )
Returns a string composed of concatenating all the elements of an array, separated by a joiner string. If array is not an array, null is returned.

• Parameters:
• array (Object): array of numbers or strings
• joiner (String): text string to interpose between adjacent elements
• Return value
• (String): string composed of array elements separated by joiner strings
• Example:
• join(array(1.5,2.1,-3.9), "; ") = "1.5; 2.1; -3.9"

dotProduct( array1, array2 )
Returns the dot (scalar) product of two numeric arrays. If either argument is not an array, or if the arrays are not of the same length, a blank value is returned.

• Parameters:
• array1 (Object): first array
• array2 (Object): second array
• Return value
• (floating point): sum of element-wise products of input arrays
• Example:
• dotProduct(array(3,4,5), array(1,2,3)) = 26

add( arrayOrScalar1, arrayOrScalar2 )
Returns the element-by-element result of adding either two numeric arrays of the same length, or an array and a scalar considered as if an array of the right length.

If the arguments are not as expected (e.g. arrays of different lengths, both scalars, not numeric) then null is returned.

• Parameters:
• arrayOrScalar1 (Object): first numeric array/scalar
• arrayOrScalar2 (Object): second numeric array/scalar
• Return value
• (array of floating point): element-by-element result of arrayOrScalar1 + arrayOrScalar2, the same length as the input array(s)
• Examples:
• add(array(1,2,3), array(0.1,0.2,0.3)) = [1.1, 2.2, 3.3]
• add(array(1,2,3), 10) = [11,12,13]

subtract( arrayOrScalar1, arrayOrScalar2 )
Returns the element-by-element result of subtracting either two numeric arrays of the same length, or an array and a scalar considered as if an array of the right length.

If the arguments are not as expected (e.g. arrays of different lengths, both scalars, not numeric) then null is returned.

• Parameters:
• arrayOrScalar1 (Object): first numeric array/scalar
• arrayOrScalar2 (Object): second numeric array/scalar
• Return value
• (array of floating point): element-by-element result of arrayOrScalar1 - arrayOrScalar2, the same length as the input array(s)
• Examples:
• subtract(array(1,2,3), array(0.1,0.2,0.3)) = [0.9, 1.8, 2.7]
• subtract(array(1,2,3), 1.0) = [0, 1, 2]

multiply( arrayOrScalar1, arrayOrScalar2 )
Returns the element-by-element result of multiplying either two numeric arrays of the same length, or an array and a scalar considered as if an array of the right length.

If the arguments are not as expected (e.g. arrays of different lengths, both scalars, not numeric) then null is returned.

• Parameters:
• arrayOrScalar1 (Object): first numeric array/scalar
• arrayOrScalar2 (Object): second numeric array/scalar
• Return value
• (array of floating point): element-by-element result of arrayOrScalar1 * arrayOrScalar2, the same length as the input array(s)
• Examples:
• multiply(array(1,2,3), array(2,4,6)) = [2, 8, 18]
• multiply(2, array(1,2,3)) = [2, 4, 6]

divide( arrayOrScalar1, arrayOrScalar2 )
Returns the element-by-element result of dividing either two numeric arrays of the same length, or an array and a scalar considered as if an array of the right length.

If the arguments are not as expected (e.g. arrays of different lengths, both scalars, not numeric) then null is returned.

• Parameters:
• arrayOrScalar1 (Object): first numeric array/scalar
• arrayOrScalar2 (Object): second numeric array/scalar
• Return value
• (array of floating point): element-by-element result of arrayOrScalar1 / arrayOrScalar2, the same length as the input array(s)
• Examples:
• divide(array(0,9,4), array(1,3,8)) = [0, 3, 0.5]
• divide(array(50,60,70), 10) = [5, 6, 7]

reciprocal( array )
Returns the result of taking the reciprocal of every element of a numeric array. If the supplied array argument is not a numeric array, null is returned.

• Parameters:
• array (Object): array input
• Return value
• (array of floating point): array output, the same length as the array parameter
• Example:
• reciprocal(array(1,2,0.25) = [1, 0.5, 4]

condition( flagArray, trueValue, falseValue )
Maps a boolean array to a numeric array by using supplied numeric values to represent true and false values from the input array.

This has the same effect as applying the expression outArray[i] = flagArray[i] ? trueValue : falseValue.

• Parameters:
• flagArray (array of boolean): array of boolean values
• trueValue (floating point): output value corresponding to an input true value
• falseValue (floating point): output value corresponding to an input false value
• Return value
• (array of floating point): output numeric array, same length as flagArray
• Example:
• condition([true, false, true], 1, 0) = [1, 0, 1]

constant( n, value )
Returns a fixed-size array filled with a given constant value.

Note: This documents the double-precision version of the routine. Corresponding routines exist for other data types (float, long, int, short, byte).

• Parameters:
• n (integer): size of output array
• value (floating point): value of every element in the output array
• Return value
• (array of floating point): n-element array with every element set to value
• Example:
• constant(5, 23.5) = [23.5, 23.5, 23.5, 23.5, 23.5]

slice( array, i0, i1 )
Returns a sub-sequence of values from a given array.

The semantics are like python array slicing, though both limits have to be specified: the output array contains the sequence of elements in the input array from i0 (inclusive) to i1 (exclusive). If a negative value is given in either case, it is added to the length of the input array, so that -1 indicates the last element of the input array. The indices are capped at 0 and the input array length respectively, so a large positive value may be used to indicate the end of the array. If the end index is less than or equal to the start index, a zero-length array is returned.

Note: This documents the double-precision version of the routine. Corresponding routines exist for other data types (float, long, int, short, byte, String, Object).

• Parameters:
• array (array of floating point): input array
• i0 (integer): index of first element, inclusive (may be negative to count back from the end)
• i1 (integer): index of the last element, exclusive (may be negative to count back from the end)
• Return value
• (array of floating point): array giving the sequence of elements specified by i0 and i1
• Examples:
• slice(array(10,11,12,13), 0, 3) = [10, 11, 12]
• slice(array(10,11,12,13), -2, 999) = [12, 13]

pick( array, indices, ... )
Returns a selection of elements from a given array.

The output array consists of one element selected from the input array for each of the supplied index values. If a negative value is supplied for an index value, it is added to the input array length, so that -1 indicates the last element of the input array. If the input array is null, null is returned. If any of the index values is out of the range of the extent of the input array, an error results.

Note: This documents the double-precision version of the routine. Corresponding routines exist for other data types (float, long, int, short, byte, String, Object).

• Parameters:
• array (array of floating point): input array
• indices (integer, one or more): one or more index into the input array (may be negative to count back from the end)
• Return value
• (array of floating point): array giving the elements specified by indices
• Examples:
• pick(array(10,11,12,13), 0, 3) = [10, 13]
• pick(array(10,11,12,13), -1, -2, -3) = [13, 12, 11]

arrayFunc( expr, inArray )
Returns a floating-point array resulting from applying a given function expression element-by-element to an input array. The output array is the same length as the input array.

The supplied expression can use the variable "x" to refer to the corresponding element of the input array, and "i" to refer to its (zero-based) index. The various functions and operators from the expression language can all be used, but it is currently not possible to reference other table column values.

If there is an error in the expression, a blank value (not an array) will be returned.

• Parameters:
• expr (String): expression mapping input to output array values
• inArray (Object): input array
• Return value
• (array of floating point): floating point array with the same number of elements as inArray, or null for a bad expr
• Examples:
• arrayFunc("3*x",array(0,1,2,3,NaN)) = [0, 3, 6, 9, NaN]
• arrayFunc("pow(2,i)+x", array(0.5,0.5,0.5,0.5)) = [1.5, 2.5, 4.5, 8.5]

intArrayFunc( expr, inArray )
Returns an integer array resulting from applying a given function expression element-by-element to an input array. The output array is the same length as the input array.

The supplied expression can use the variable "x" to refer to the corresponding element of the input array, and "i" to refer to its (zero-based) index. The various functions and operators from the expression language can all be used, but it is currently not possible to reference other table column values.

If there is an error in the expression, a blank value (not an array) will be returned.

• Parameters:
• expr (String): expression mapping input to output array values
• inArray (Object): input array
• Return value
• (array of integer): floating point array with the same number of elements as inArray, or null for a bad expr
• Example:
• intArrayFunc("-x",sequence(5)) = [0, -1, -2, -3, -4]

indexOf( array, item )
Returns the position in a supplied array at which a given item appears. The result is zero-based, so if the supplied item is the first entry in the array, the return value will be zero.

If the item does not appear in the array, -1 is returned. If it appears multiple times, the index of its first appearance is returned.

If indexOf(array, item)==n, then array[n] is equal to item.

Note: This documents the Object version of the routine. Corresponding routines exist for other data types (double, float, long, int, short).

• Parameters:
• array (array of Object): array which may contain the supplied item
• item (Object): entry to look for in the array
• Return value
• (integer): the index of item in array, or -1
• Examples:
• indexOf(stringArray("QSO", "BCG", "SNR"), "BCG") = 1
• indexOf(stringArray("QSO", "BCG", "SNR"), "TLA") = -1

sequence( n )
Returns an integer array of a given length with the values 0, 1, 2, ....

• Parameters:
• n (integer): length of array
• Return value
• (array of integer): n-element array, (0, 1, 2, ... n-1)
• Example:
• sequence(4) = (0, 1, 2, 3)

sequence( n, start, step )
Returns a double array of a given length with values starting at a given value and increasing with a given increment.

• Parameters:
• n (integer): length of array
• start (floating point): value of first element
• step (floating point): increment to apply to each element
• Return value
• (array of floating point): n-element array, (start, start+step, start+2*step, ... start+(n-1)*step)
• Example:
• sequence(4, 100, 0.1) = (100.0, 100.1, 100.2, 100.3)

array( values, ... )
Returns a floating point numeric array built from the given arguments.

• Parameters:
• values (floating point, one or more): one or more array elements
• Return value
• (array of floating point): array

intArray( values, ... )
Returns an integer numeric array built from the given arguments.

• Parameters:
• values (integer, one or more): one or more array elements
• Return value
• (array of integer): array

stringArray( values, ... )
Returns a String array built from the given arguments.

• Parameters:
• values (String, one or more): one or more array elements
• Return value
• (array of String): array

#### 10.6.3 Bits

Bit manipulation functions.

Note that for bitwise AND, OR, XOR of integer values etc you can use the java bitwise operators "&", "|", "^".

hasBit( value, bitIndex )
Determines whether a given integer has a certain bit set to 1.

• Parameters:
• value (long integer): integer whose bits are to be tested
• bitIndex (integer): index of bit to be tested in range 0..63, where 0 is the least significant bit
• Return value
• (boolean): true if bit is set; more or less equivalent to (value & 1L<<bitIndex) != 0
• Examples:
• hasBit(64, 6) = true
• hasBit(63, 6) = false

bitCount( i )
Returns the number of set bits in the 64-bit two's complement representation of the integer argument.

• Parameters:
• i (long integer): integer value
• Return value
• (integer): number of "1" bits in the binary representation of i
• Examples:
• bitCount(64) = 1
• bitCount(3) = 2

toBinary( value )
Converts the integer argument to a binary string consisting only of 1s and 0s.

• Parameters:
• value (long integer): integer value
• Return value
• (String): binary representation of value
• Examples:
• toBinary(42) = "101010"
• toBinary(255^7) = "11111000"

fromBinary( binVal )
Converts a string representing a binary number to its integer value.

• Parameters:
• binVal (String): binary representation of value
• Return value
• (integer): integer value represented by binary string binVal
• Example:
• fromBinary("101010") = 42

#### 10.6.4 Conversions

Functions for converting between strings and numeric values.

toString( fpVal )
Turns a numeric value into a string.

• Parameters:
• fpVal (floating point): floating point numeric value
• Return value
• (String): a string representation of fpVal

toString( intVal )
Turns an integer numeric value into a string.

• Parameters:
• intVal (long integer): integer numeric value
• Return value
• (String): a string representation of intVal

toString( charVal )
Turns a single character value into a string.

• Parameters:
• charVal (char): character numeric value
• Return value
• (String): a string representation of charVal

toString( byteVal )
Turns a byte value into a string.

• Parameters:
• byteVal (byte): byte numeric value
• Return value
• (String): a string representation of byteVal

toString( booleanVal )
Turns a boolean value into a string.

• Parameters:
• booleanVal (boolean): boolean value (true or false)
• Return value
• (String): a string representation of booleanVal ("true" or "false")

toString( objVal )
Turns any object value into a string. As applied to existing string values this isn't really useful, but it means that you can apply toString to any object value without knowing its type and get a useful return from it.

• Parameters:
• objVal (Object): non-primitive value
• Return value
• (String): a string representation of objVal

parseByte( str )
Attempts to interpret a string as a byte (8-bit signed integer) value. If the input string can't be interpreted in this way, a blank value will result.

• Parameters:
• str (String): string containing numeric representation
• Return value
• (byte): byte value of str

parseShort( str )
Attempts to interpret a string as a short (16-bit signed integer) value. If the input string can't be interpreted in this way, a blank value will result.

• Parameters:
• str (String): string containing numeric representation
• Return value
• (short integer): byte value of str

parseInt( str )
Attempts to interpret a string as an int (32-bit signed integer) value. If the input string can't be interpreted in this way, a blank value will result.

• Parameters:
• str (String): string containing numeric representation
• Return value
• (integer): byte value of str

parseLong( str )
Attempts to interpret a string as a long (64-bit signed integer) value. If the input string can't be interpreted in this way, a blank value will result.

• Parameters:
• str (String): string containing numeric representation
• Return value
• (long integer): byte value of str

parseFloat( str )
Attempts to interpret a string as a float (32-bit floating point) value. If the input string can't be interpreted in this way, a blank value will result.

• Parameters:
• str (String): string containing numeric representation
• Return value
• (floating point): byte value of str

parseDouble( str )
Attempts to interpret a string as a double (64-bit signed integer) value. If the input string can't be interpreted in this way, a blank value will result.

• Parameters:
• str (String): string containing numeric representation
• Return value
• (floating point): byte value of str

parseBigInteger( str )
Attempts to interpret a string as a "BigInteger" value. This can be used for working with string representations of integers that can't be stored as an unsigned 64-bit value.

The result is a BigInteger object, which can't be used in normal numeric expressions, but has a number of methods defined on it for comparison, arithmetic, bit manipulation etc. See the java.math.BigInteger javadocs for details.

• Parameters:
• str (String): string containing numeric representation
• Return value
• (BigInteger): BigInteger value of str
• Examples:
• parseBigInteger("-20000000000000000023").doubleValue() = -2e19
• parseBigInteger("18446744073709551616").testBit(64) = true

parseBigDecimal( str )
Attempts to interpret a string as a "BigDecimal" value. This can be used for working with string representations of non-integer values that require more precision or range than is possible in a 64-bit IEEE-754 double precision variable.

The result is a BigDecimal object, which can't be used in normal numeric expressions, but has a number of methods defined on it for comparison, arithmetic, bit manipulation etc. See the java.math.BigDecimal javadocs for details.

• Parameters:
• str (String): string contining numeric representation
• Return value
• (BigDecimal): BigDecimal value of str
• Example:
• parseBigDecimal("101").compareTo(parseBigDecimal("102")) = -1

parseInts( str )
Attempts to interpret a string as an array of integer values. An ad-hoc algorithm is used that tries to extract a list of integers from a string; a comma- or space-separated list of integer values will work, and other formats may or may not.

The details of this function's behaviour may change in future releases.

• Parameters:
• str (String): string containing a list of integer values
• Return value
• (array of integer): array of integer values
• Examples:
• parseInts("9 8 -23") = [9, 8, -23]
• parseInts("tiddly-pom") = []

parseDoubles( str )
Attempts to interpret a string as an array of floating point values. An ad-hoc algorithm is used that tries to extract a list of numeric values from a string; a comma- or space-separated list of floating point values will work, and other formats may or may not.

This function can be used as a hacky way to extract the numeric values from an STC-S (for instance ObsCore/EPNcore s_region) string.

The details of this function's behaviour may change in future releases.

• Parameters:
• str (String): string containing a list of floating point values
• Return value
• (array of floating point): array of floating point values
• Examples:
• parseDoubles("1.3, 99e1, NaN, -23") = [1.3, 990.0, NaN, -23.0]
• parseDoubles("Polygon ICRS 0.8 2.1 9.0 2.1 6.2 8.6") = [0.8, 2.1, 9.0, 2.1, 6.2, 8.6]
• parseDoubles("La la la") = []

toByte( value )
Attempts to convert the numeric argument to a byte (8-bit signed integer) result. If it is out of range, a blank value will result.

• Parameters:
• value (floating point): numeric value for conversion
• Return value
• (byte): value converted to type byte

toShort( value )
Attempts to convert the numeric argument to a short (16-bit signed integer) result. If it is out of range, a blank value will result.

• Parameters:
• value (floating point): numeric value for conversion
• Return value
• (short integer): value converted to type short

toInteger( value )
Attempts to convert the numeric argument to an int (32-bit signed integer) result. If it is out of range, a blank value will result.

• Parameters:
• value (floating point): numeric value for conversion
• Return value
• (integer): value converted to type int

toLong( value )
Attempts to convert the numeric argument to a long (64-bit signed integer) result. If it is out of range, a blank value will result.

• Parameters:
• value (floating point): numeric value for conversion
• Return value
• (long integer): value converted to type long

toFloat( value )
Attempts to convert the numeric argument to a float (32-bit floating point) result. If it is out of range, a blank value will result.

• Parameters:
• value (floating point): numeric value for conversion
• Return value
• (floating point): value converted to type float

toDouble( value )
Converts the numeric argument to a double (64-bit signed integer) result.

• Parameters:
• value (floating point): numeric value for conversion
• Return value
• (floating point): value converted to type double

toHex( value )
Converts the integer argument to hexadecimal form.

• Parameters:
• value (long integer): integer value
• Return value
• (String): hexadecimal representation of value
• Example:
• toHex(42) = "2a"

fromHex( hexVal )
Converts a string representing a hexadecimal number to its integer value.

• Parameters:
• hexVal (String): hexadecimal representation of value
• Return value
• (integer): integer value represented by hexVal
• Example:
• fromHex("2a") = 42

#### 10.6.5 CoordsDegrees

Functions for angle transformations and manipulations, with angles generally in degrees. In particular, methods for translating between degrees and HH:MM:SS.S or DDD:MM:SS.S type sexagesimal representations are provided.

degreesToDms( deg )
Converts an angle in degrees to a formatted degrees:minutes:seconds string. No fractional part of the seconds field is given.

• Parameters:
• deg (floating point): angle in degrees
• Return value
• (String): DMS-format string representing deg

degreesToDms( deg, secFig )
Converts an angle in degrees to a formatted degrees:minutes:seconds string with a given number of decimal places in the seconds field.

• Parameters:
• deg (floating point): angle in degrees
• secFig (integer): number of decimal places in the seconds field
• Return value
• (String): DMS-format string representing deg

degreesToHms( deg )
Converts an angle in degrees to a formatted hours:minutes:seconds string. No fractional part of the seconds field is given.

• Parameters:
• deg (floating point): angle in degrees
• Return value
• (String): HMS-format string representing deg

degreesToHms( deg, secFig )
Converts an angle in degrees to a formatted hours:minutes:seconds string with a given number of decimal places in the seconds field.

• Parameters:
• deg (floating point): angle in degrees
• secFig (integer): number of decimal places in the seconds field
• Return value
• (String): HMS-format string representing deg

dmsToDegrees( dms )
Converts a formatted degrees:minutes:seconds string to an angle in degrees. Delimiters may be colon, space, characters dm[s], or some others. Additional spaces and leading +/- are permitted. The :seconds part is optional.

• Parameters:
• dms (String): formatted DMS string
• Return value
• (floating point): angle in degrees specified by dms

hmsToDegrees( hms )
Converts a formatted hours:minutes:seconds string to an angle in degrees. Delimiters may be colon, space, characters hm[s], or some others. Additional spaces and leading +/- are permitted. The :seconds part is optional.

• Parameters:
• hms (String): formatted HMS string
• Return value
• (floating point): angle in degrees specified by hms

dmsToDegrees( deg, min, sec )
Converts degrees, minutes, seconds to an angle in degrees.

In conversions of this type, one has to be careful to get the sign right in converting angles which are between 0 and -1 degrees. This routine uses the sign bit of the deg argument, taking care to distinguish between +0 and -0 (their internal representations are different for floating point values). It is illegal for the min or sec arguments to be negative.

• Parameters:
• deg (floating point): degrees part of angle
• min (floating point): minutes part of angle
• sec (floating point): seconds part of angle
• Return value
• (floating point): specified angle in degrees

hmsToDegrees( hour, min, sec )
Converts hours, minutes, seconds to an angle in degrees.

In conversions of this type, one has to be careful to get the sign right in converting angles which are between 0 and -1 hours. This routine uses the sign bit of the hour argument, taking care to distinguish between +0 and -0 (their internal representations are different for floating point values).

• Parameters:
• hour (floating point): degrees part of angle
• min (floating point): minutes part of angle
• sec (floating point): seconds part of angle
• Return value
• (floating point): specified angle in degrees

skyDistanceDegrees( ra1, dec1, ra2, dec2 )
Calculates the separation (distance around a great circle) of two points on the sky in degrees.

• Parameters:
• ra1 (floating point): right ascension of point 1 in degrees
• dec1 (floating point): declination of point 1 in degrees
• ra2 (floating point): right ascension of point 2 in degrees
• dec2 (floating point): declination of point 2 in degrees
• Return value
• (floating point): angular distance between point 1 and point 2 in degrees

posAngDegrees( ra1, dec1, ra2, dec2 )
Calculates the position angle between two points on the sky in degrees. The result is in the range +/-180. If point 2 is due east of point 1, the result is +90. Zero is returned if the points are coincident.

• Parameters:
• ra1 (floating point): right ascension of point 1 in degrees
• dec1 (floating point): declination of point 1 in degrees
• ra2 (floating point): right ascension of point 2 in degrees
• dec2 (floating point): declination of point 2 in degrees
• Return value
• (floating point): bearing in degrees of point 2 from point 1.

polarDistanceDegrees( ra1, dec1, radius1, ra2, dec2, radius2 )
Calculates the distance in three dimensional space between two points specified in spherical polar coordinates.

• Parameters:
• ra1 (floating point): right ascension of point 1 in degrees
• dec1 (floating point): declination of point1 in degrees
• radius1 (floating point): distance from origin of point1
• ra2 (floating point): right ascension of point 2 in degrees
• dec2 (floating point): declination of point2 in degrees
• radius2 (floating point): distance from origin of point2
• Return value
• (floating point): the linear distance between point1 and point2; units are as for radius1 and radius2

Functions for angle transformations and manipulations, based on radians rather than degrees. In particular, methods for translating between radians and HH:MM:SS.S or DDD:MM:SS.S type sexagesimal representations are provided.

radiansToDms( rad )
Converts an angle in radians to a formatted degrees:minutes:seconds string. No fractional part of the seconds field is given.

• Parameters:
• rad (floating point): angle in radians
• Return value
• (String): DMS-format string representing rad

radiansToDms( rad, secFig )
Converts an angle in radians to a formatted degrees:minutes:seconds string with a given number of decimal places in the seconds field.

• Parameters:
• rad (floating point): angle in radians
• secFig (integer): number of decimal places in the seconds field
• Return value
• (String): DMS-format string representing rad

radiansToHms( rad )
Converts an angle in radians to a formatted hours:minutes:seconds string. No fractional part of the seconds field is given.

• Parameters:
• rad (floating point): angle in radians
• Return value
• (String): HMS-format string representing rad

radiansToHms( rad, secFig )
Converts an angle in radians to a formatted hours:minutes:seconds string with a given number of decimal places in the seconds field.

• Parameters:
• rad (floating point): angle in radians
• secFig (integer): number of decimal places in the seconds field
• Return value
• (String): HMS-format string representing rad

dmsToRadians( dms )
Converts a formatted degrees:minutes:seconds string to an angle in radians. Delimiters may be colon, space, characters dm[s], or some others. Additional spaces and leading +/- are permitted. The :seconds part is optional.

• Parameters:
• dms (String): formatted DMS string
• Return value
• (floating point): angle in radians specified by dms

hmsToRadians( hms )
Converts a formatted hours:minutes:seconds string to an angle in radians. Delimiters may be colon, space, characters hm[s], or some others. Additional spaces and leading +/- are permitted. The :seconds part is optional.

• Parameters:
• hms (String): formatted HMS string
• Return value
• (floating point): angle in radians specified by hms

dmsToRadians( deg, min, sec )
Converts degrees, minutes, seconds to an angle in radians.

In conversions of this type, one has to be careful to get the sign right in converting angles which are between 0 and -1 degrees. This routine uses the sign bit of the deg argument, taking care to distinguish between +0 and -0 (their internal representations are different for floating point values). It is illegal for the min or sec arguments to be negative.

• Parameters:
• deg (floating point): degrees part of angle
• min (floating point): minutes part of angle
• sec (floating point): seconds part of angle
• Return value
• (floating point): specified angle in radians

hmsToRadians( hour, min, sec )
Converts hours, minutes, seconds to an angle in radians.

In conversions of this type, one has to be careful to get the sign right in converting angles which are between 0 and -1 hours. This routine uses the sign bit of the hour argument, taking care to distinguish between +0 and -0 (their internal representations are different for floating point values).

• Parameters:
• hour (floating point): degrees part of angle
• min (floating point): minutes part of angle
• sec (floating point): seconds part of angle
• Return value
• (floating point): specified angle in radians

skyDistanceRadians( ra1, dec1, ra2, dec2 )
Calculates the separation (distance around a great circle) of two points on the sky in radians.

• Parameters:
• ra1 (floating point): right ascension of point 1 in radians
• dec1 (floating point): declination of point 1 in radians
• ra2 (floating point): right ascension of point 2 in radians
• dec2 (floating point): declination of point 2 in radians
• Return value
• (floating point): angular distance between point 1 and point 2 in radians

posAngRadians( ra1, dec1, ra2, dec2 )
Calculates the position angle between two points on the sky in radians. The result is in the range +/-pi. If point 2 is due east of point 1, the result is +pi/2. Zero is returned if the points are coincident.

• Parameters:
• ra1 (floating point): right ascension of point 1 in radians
• dec1 (floating point): declination of point 1 in radians
• ra2 (floating point): right ascension of point 2 in radians
• dec2 (floating point): declination of point 2 in radians
• Return value
• (floating point): bearing in radians of point 2 from point 1

polarDistanceRadians( ra1, dec1, radius1, ra2, dec2, radius2 )
Calculates the distance in three dimensional space between two points specified in spherical polar coordinates.

• Parameters:
• ra1 (floating point): right ascension of point 1 in radians
• dec1 (floating point): declination of point1 in radians
• radius1 (floating point): distance from origin of point1
• ra2 (floating point): right ascension of point 2 in radians
• dec2 (floating point): declination of point2 in radians
• radius2 (floating point): distance from origin of point2
• Return value
• (floating point): the linear distance between point1 and point2; units are as for radius1 and radius2

hoursToRadians( hours )

• Parameters:
• hours (floating point): angle in hours
• Return value
• (floating point): angle in radians

degreesToRadians( deg )

• Parameters:
• deg (floating point): angle in degrees
• Return value
• (floating point): angle in radians

radiansToDegrees( rad )

• Parameters:
• rad (floating point): angle in radians
• Return value
• (floating point): angle in degrees

raFK4toFK5radians( raFK4, decFK4 )
Converts a B1950.0 FK4 position to J2000.0 FK5 at an epoch of B1950.0 yielding Right Ascension. This assumes zero proper motion in the FK5 frame.

• Parameters:
• raFK4 (floating point): right ascension in B1950.0 FK4 system (radians)
• decFK4 (floating point): declination in B1950.0 FK4 system (radians)
• Return value
• (floating point): right ascension in J2000.0 FK5 system (radians)

decFK4toFK5radians( raFK4, decFK4 )
Converts a B1950.0 FK4 position to J2000.0 FK5 at an epoch of B1950.0 yielding Declination This assumes zero proper motion in the FK5 frame.

• Parameters:
• raFK4 (floating point): right ascension in B1950.0 FK4 system (radians)
• decFK4 (floating point): declination in B1950.0 FK4 system (radians)
• Return value
• (floating point): declination in J2000.0 FK5 system (radians)

raFK5toFK4radians( raFK5, decFK5 )
Converts a J2000.0 FK5 position to B1950.0 FK4 at an epoch of B1950.0 yielding Declination. This assumes zero proper motion, parallax and radial velocity in the FK5 frame.

• Parameters:
• raFK5 (floating point): right ascension in J2000.0 FK5 system (radians)
• decFK5 (floating point): declination in J2000.0 FK5 system (radians)
• Return value
• (floating point): right ascension in the FK4 system (radians)

decFK5toFK4radians( raFK5, decFK5 )
Converts a J2000.0 FK5 position to B1950.0 FK4 at an epoch of B1950.0 yielding Declination. This assumes zero proper motion, parallax and radial velocity in the FK5 frame.

• Parameters:
• raFK5 (floating point): right ascension in J2000.0 FK5 system (radians)
• decFK5 (floating point): declination in J2000.0 FK5 system (radians)
• Return value
• (floating point): right ascension in the FK4 system (radians)

raFK4toFK5Radians( raFK4, decFK4, bepoch )
Converts a B1950.0 FK4 position to J2000.0 FK5 yielding Right Ascension. This assumes zero proper motion in the FK5 frame. The bepoch parameter is the epoch at which the position in the FK4 frame was determined.

• Parameters:
• raFK4 (floating point): right ascension in B1950.0 FK4 system (radians)
• decFK4 (floating point): declination in B1950.0 FK4 system (radians)
• bepoch (floating point): Besselian epoch
• Return value
• (floating point): right ascension in J2000.0 FK5 system (radians)

decFK4toFK5Radians( raFK4, decFK4, bepoch )
Converts a B1950.0 FK4 position to J2000.0 FK5 yielding Declination. This assumes zero proper motion in the FK5 frame. The bepoch parameter is the epoch at which the position in the FK4 frame was determined.

• Parameters:
• raFK4 (floating point): right ascension in B1950.0 FK4 system (radians)
• decFK4 (floating point): declination in B1950.0 FK4 system (radians)
• bepoch (floating point): Besselian epoch
• Return value
• (floating point): declination in J2000.0 FK5 system (radians)

raFK5toFK4Radians( raFK5, decFK5, bepoch )
Converts a J2000.0 FK5 position to B1950.0 FK4 yielding Declination. This assumes zero proper motion, parallax and radial velocity in the FK5 frame.

• Parameters:
• raFK5 (floating point): right ascension in J2000.0 FK5 system (radians)
• decFK5 (floating point): declination in J2000.0 FK5 system (radians)
• bepoch (floating point): Besselian epoch
• Return value
• (floating point): right ascension in the FK4 system (radians)

decFK5toFK4Radians( raFK5, decFK5, bepoch )
Converts a J2000.0 FK5 position to B1950.0 FK4 yielding Declination. This assumes zero proper motion, parallax and radial velocity in the FK5 frame.

• Parameters:
• raFK5 (floating point): right ascension in J2000.0 FK5 system (radians)
• decFK5 (floating point): declination in J2000.0 FK5 system (radians)
• bepoch (floating point): Besselian epoch
• Return value
• (floating point): right ascension in the FK4 system (radians)

DEGREE_RADIANS
The size of one degree in radians.

HOUR_RADIANS
The size of one hour of right ascension in radians.

ARC_MINUTE_RADIANS
The size of one arcminute in radians.

ARC_SECOND_RADIANS
The size of one arcsecond in radians.

#### 10.6.7 Coverage

Functions related to coverage and footprints.

One coverage standard is Multi-Order Coverage maps, described at http://www.ivoa.net/Documents/MOC/. MOC positions are always defined in ICRS equatorial coordinates.

MOC locations may be given as either the filename or the URL of a MOC FITS file. Alternatively, they may be the identifier of a VizieR table, for instance "V/139/sdss9" (SDSS DR9). A list of all the MOCs available from VizieR can currently be found at http://alasky.u-strasbg.fr/footprints/tables/vizier/. You can search for VizieR table identifiers from the VizieR web page (http://vizier.u-strasbg.fr/); note you must use the table identifier (like "V/139/sdss9") and not the catalogue identifier (like "V/139").

inMoc( mocLocation, ra, dec )
Indicates whether a given sky position falls strictly within a given MOC (Multi-Order Coverage map). If the given mocLocation value does not represent a MOC (for instance no file exists or the file is not in MOC format) a warning will be issued the first time it's referenced, and the result will be false.

• Parameters:
• mocLocation (String): location of a FITS MOC file: a filename, a URL, or a VizieR table name
• ra (floating point): ICRS right ascension in degrees
• dec (floating point): ICRS declination in degrees
• Return value
• (boolean): true iff the given position falls within the given MOC

nearMoc( mocLocation, ra, dec, distanceDeg )
Indicates whether a given sky position either falls within, or is within a certain distance of the edge of, a given MOC (Multi-Order Coverage map). If the given mocLocation value does not represent a MOC (for instance no file exists or the file is not in MOC format) a warning will be issued the first time it's referenced, and the result will be false.

• Parameters:
• mocLocation (String): location of a FITS MOC file: a filename, a URL, or a VizieR table name
• ra (floating point): ICRS right ascension in degrees
• dec (floating point): ICRS declination in degrees
• distanceDeg (floating point): permitted distance from MOC boundary in degrees
• Return value
• (boolean): true iff the given position is within distance degrees of the given MOC

#### 10.6.8 Distances

Functions for converting between different measures of cosmological distance.

The following parameters are used:

• z: redshift
• H0: Hubble constant in km/sec/Mpc (example value ~70)
• omegaM: Density ratio of the universe (example value 0.3)
• omegaLambda: Normalised cosmological constant (example value 0.7)

For a flat universe, omegaM+omegaLambda=1

The terms and formulae used here are taken from the paper by D.W.Hogg, Distance measures in cosmology, astro-ph/9905116 v4 (2000).

MpcToM( distMpc )
Converts from MegaParsecs to metres.

• Parameters:
• distMpc (floating point): distance in Mpc
• Return value
• (floating point): distance in m

mToMpc( distM )
Converts from metres to MegaParsecs.

• Parameters:
• distM (floating point): distance in m
• Return value
• (floating point): distance in Mpc

zToDist( z )
Quick and dirty function for converting from redshift to distance.

Warning: this makes some reasonable assumptions about the cosmology and returns the luminosity distance. It is only intended for approximate use. If you care about the details, use one of the more specific functions here.

• Parameters:
• z (floating point): redshift
• Return value
• (floating point): some distance measure in Mpc

zToAge( z )
Quick and dirty function for converting from redshift to time.

Warning: this makes some reasonable assumptions about the cosmology. It is only intended for approximate use. If you care about the details use one of the more specific functions here.

• Parameters:
• z (floating point): redshift
• Return value
• (floating point): 'age' of photons from redshift z in Gyr

comovingDistanceL( z, H0, omegaM, omegaLambda )
Line-of-sight comoving distance.

• Parameters:
• z (floating point): redshift
• H0 (floating point): Hubble constant in km/sec/Mpc
• omegaM (floating point): density ratio of the universe
• omegaLambda (floating point): normalised cosmological constant
• Return value
• (floating point): line-of-sight comoving distance in Mpc

comovingDistanceT( z, H0, omegaM, omegaLambda )
Transverse comoving distance.

• Parameters:
• z (floating point): redshift
• H0 (floating point): Hubble constant in km/sec/Mpc
• omegaM (floating point): density ratio of the universe
• omegaLambda (floating point): normalised cosmological constant
• Return value
• (floating point): transverse comoving distance in Mpc

angularDiameterDistance( z, H0, omegaM, omegaLambda )
Angular diameter distance.

• Parameters:
• z (floating point): redshift
• H0 (floating point): Hubble constant in km/sec/Mpc
• omegaM (floating point): density ratio of the universe
• omegaLambda (floating point): normalised cosmological constant
• Return value
• (floating point): angular diameter distance in Mpc

luminosityDistance( z, H0, omegaM, omegaLambda )
Luminosity distance.

• Parameters:
• z (floating point): redshift
• H0 (floating point): Hubble constant in km/sec/Mpc
• omegaM (floating point): density ratio of the universe
• omegaLambda (floating point): normalised cosmological constant
• Return value
• (floating point): luminosity distance in Mpc

lookbackTime( z, H0, omegaM, omegaLambda )
Lookback time. This returns the difference between the age of the universe at time of observation (now) and the age of the universe at the time when photons of redshift z were emitted.

• Parameters:
• z (floating point): redshift
• H0 (floating point): Hubble constant in km/sec/Mpc
• omegaM (floating point): density ratio of the universe
• omegaLambda (floating point): normalised cosmological constant
• Return value
• (floating point): lookback time in Gyr

comovingVolume( z, H0, omegaM, omegaLambda )
Comoving volume. This returns the all-sky total comoving volume out to a given redshift z.

• Parameters:
• z (floating point): redshift
• H0 (floating point): Hubble constant in km/sec/Mpc
• omegaM (floating point): density ratio of the universe
• omegaLambda (floating point): normalised cosmological constant
• Return value
• (floating point): comoving volume in Gpc3

SPEED_OF_LIGHT
Speed of light in m/s.

METRE_PER_PARSEC
Number of metres in a parsec.

SEC_PER_YEAR
Number of seconds in a year.

#### 10.6.9 Fluxes

Functions for conversion between flux and magnitude values. Functions are provided for conversion between flux in Janskys and AB magnitudes.

Some constants for approximate conversions between different magnitude scales are also provided:

• Constants JOHNSON_AB_*, for Johnson <-> AB magnitude conversions, from Frei and Gunn, Astronomical Journal 108, 1476 (1994), Table 2 (1994AJ....108.1476F).
• Constants VEGA_AB_*, for Vega <-> AB magnitude conversions, from Blanton et al., Astronomical Journal 129, 2562 (2005), Eqs. (5) (2005AJ....129.2562B).

abToJansky( magAB )
Converts AB magnitude to flux in Jansky.

F/Jy=10(23-(AB+48.6)/2.5)

• Parameters:
• magAB (floating point): AB magnitude value
• Return value
• (floating point): equivalent flux in Jansky

janskyToAb( fluxJansky )
Converts flux in Jansky to AB magnitude.

AB=2.5*(23-log10(F/Jy))-48.6

• Parameters:
• fluxJansky (floating point): flux in Jansky
• Return value
• (floating point): equivalent AB magnitude

luminosityToFlux( lumin, dist )
Converts luminosity to flux given a luminosity distance.

F=lumin/(4 x Pi x dist2)

• Parameters:
• lumin (floating point): luminosity
• dist (floating point): luminosity distance
• Return value
• (floating point): equivalent flux

fluxToLuminosity( flux, dist )
Converts flux to luminosity given a luminosity distance.

lumin=(4 x Pi x dist2) F

• Parameters:
• flux (floating point): flux
• dist (floating point): luminosity distance
• Return value
• (floating point): equivalent luminosity

JOHNSON_AB_V
Approximate offset between Johnson and AB magnitudes in V band. VJ~=VAB+JOHNSON_AB_V.

JOHNSON_AB_B
Approximate offset between Johnson and AB magnitudes in B band. BJ~=BAB+JOHNSON_AB_B.

JOHNSON_AB_Bj
Approximate offset between Johnson and AB magnitudes in Bj band. BjJ~=BjAB+JOHNSON_AB_Bj.

JOHNSON_AB_R
Approximate offset between Johnson and AB magnitudes in R band. RJ~=RAB+JOHNSON_AB_R.

JOHNSON_AB_I
Approximate offset between Johnson and AB magnitudes in I band. IJ~=IAB+JOHNSON_AB_I.

JOHNSON_AB_g
Approximate offset between Johnson and AB magnitudes in g band. gJ~=gAB+JOHNSON_AB_g.

JOHNSON_AB_r
Approximate offset between Johnson and AB magnitudes in r band. rJ~=rAB+JOHNSON_AB_r.

JOHNSON_AB_i
Approximate offset between Johnson and AB magnitudes in i band. iJ~=iAB+JOHNSON_AB_i.

JOHNSON_AB_Rc
Approximate offset between Johnson and AB magnitudes in Rc band. RcJ~=RcAB+JOHNSON_AB_Rc.

JOHNSON_AB_Ic
Approximate offset between Johnson and AB magnitudes in Ic band. IcJ~=IcAB+JOHNSON_AB_Ic.

JOHNSON_AB_uPrime
Offset between Johnson and AB magnitudes in u' band (zero). u'J=u'AB+JOHNSON_AB_uPrime=u'AB.

JOHNSON_AB_gPrime
Offset between Johnson and AB magnitudes in g' band (zero). g'J=g'AB+JOHNSON_AB_gPrime=g'AB.

JOHNSON_AB_rPrime
Offset between Johnson and AB magnitudes in r' band (zero). r'J=r'AB+JOHNSON_AB_rPrime=r'AB.

JOHNSON_AB_iPrime
Offset between Johnson and AB magnitudes in i' band (zero). i'J=i'AB+JOHNSON_AB_iPrime=i'AB.

JOHNSON_AB_zPrime
Offset between Johnson and AB magnitudes in z' band (zero). z'J=z'AB+JOHNSON_AB_zPrime=z'AB.

VEGA_AB_J
Approximate offset between Vega (as in 2MASS) and AB magnitudes in J band. JVega~=JAB+VEGA_AB_J.

VEGA_AB_H
Approximate offset between Vega (as in 2MASS) and AB magnitudes in H band. HVega~=HAB+VEGA_AB_H.

VEGA_AB_K
Approximate offset between Vega (as in 2MASS) and AB magnitudes in K band. KVega~=KAB+VEGA_AB_K.

#### 10.6.10 Formats

Functions for formatting numeric values.

formatDecimal( value, dp )
Turns a floating point value into a string with a given number of decimal places using standard settings.

• Parameters:
• value (floating point): value to format
• dp (integer): number of decimal places (digits after the decmal point)
• Return value
• (String): formatted string
• Examples:
• formatDecimal(PI,0) = "3."
• formatDecimal(0,10) = ".0000000000"
• formatDecimal(E*10,3) = "27.183"

formatDecimalLocal( value, dp )
Turns a floating point value into a string using current locale settings. For instance if language is set to French, decimal points will be represented as a comma "," instead of a full stop ".". Otherwise behaves the same as the corresponding formatDecimal function.

• Parameters:
• value (floating point): value to format
• dp (integer): number of decimal places (digits after the decmal point)
• Return value
• (String): formatted string
• Examples:
• formatDecimal(PI,0) = "3,"
• formatDecimal(0,10) = ",0000000000"
• formatDecimal(E*10,3) = "27,183"

formatDecimal( value, format )
Turns a floating point value into a formatted string using standard settings. The format string is as defined by Java's java.text.DecimalFormat class.

• Parameters:
• value (floating point): value to format
• format (String): format specifier
• Return value
• (String): formatted string
• Examples:
• formatDecimal(99, "#.000") = "99.000"
• formatDecimal(PI, "+0.##;-0.##") = "+3.14"

formatDecimalLocal( value, format )
Turns a floating point value into a formatted string using current locale settings. For instance if language is set to French, decimal points will be represented as a comma "," instead of a full stop ".". Otherwise behaves the same as the corresponding formatDecimal function.

• Parameters:
• value (floating point): value to format
• format (String): format specifier
• Return value
• (String): formatted string
• Examples:
• formatDecimal(99, "#.000") = "99,000"
• formatDecimal(PI, "+0.##;-0.##") = "+3,14"

#### 10.6.11 Gaia

Functions related to astrometry suitable for use with data from the Gaia astrometry mission.

The methods here are not specific to the Gaia mission, but the parameters of the functions and their units are specified in a form that is convenient for use with Gaia data, in particular the gaia_source catalogue available from http://gea.esac.esa.int/archive/ and copies or mirrors.

There are currently three main sets of functions here:

• position and velocity vector calculation and manipulation
• distance estimation from parallaxes
• astrometry propagation to different epochs

Position and velocity vectors

Functions are provided for converting the astrometric parameters contained in the Gaia catalogue to ICRS Cartesian position (XYZ) and velocity (UVW) vectors. Functions are also provided to convert these vectors between ICRS and Galactic or Ecliptic coordinates. The calculations are fairly straightforward, and follow the equations laid out in section 1.5.6 of The Hipparcos and Tycho Catalogues, ESA SP-1200 (1997) and also section 3.1.7 of the Gaia DR2 documentation (2018).

These functions will often be combined; for instance to calculate the position and velocity in galactic coordinates from Gaia catalogue values, the following expressions may be useful:

    xyz_gal = icrsToGal(astromXYZ(ra,dec,parallax))

though note that these particular examples simply invert parallax to provide distance estimates, which is not generally valid. Note also that these functions do not attempt to correct for solar motion. Such adjustments should be carried out by hand on the results of these functions if they are required.

Functions for calculating errors on the Cartesian components based on the error and correlation quantities from the Gaia catalogue are not currently provided. They would require fairly complicated invocations. If there is demand they may be implemented in the future.

Distance estimation

Gaia measures parallaxes, but some scientific use cases require the radial distance instead. While distance in parsec is in principle the reciprocal of parallax in arcsec, in the presence of non-negligable errors on measured parallax, this inversion does not give a good estimate of distance. A thorough discussion of this topic and approaches to estimating distances for Gaia-like data can be found in the papers

• C.A.L.Bailer-Jones, "Estimating distances from parallaxes", PASP 127, p994 (2015) 2015PASP..127..994B
• T.L.Astraatmadja and C.A.L.Bailer-Jones, "Estimating Distances from Parallaxes. II. Performance of Bayesian Distance Estimators on a Gaia-like Catalogue", ApJ 832, a137 (2016) 2016ApJ...832..137A
• X.Luri et al., "Gaia Data Release 2: Using Gaia Parallaxes", A&A in press (2018) arXiv:1804.09376

The functions provided here correspond to calculations from Astraatmadja & Bailer-Jones, "Estimating Distances from Parallaxes. III. Distances of Two Million Stars in the Gaia DR1 Catalogue", ApJ 833, a119 (2016) 2016ApJ...833..119A based on the Exponentially Decreasing Space Density prior defined therein. This implementation was written with reference to the Java implementation by Enrique Utrilla (DPAC).

These functions are parameterised by a length scale L that defines the exponential decay (the mode of the prior PDF is at r=2L). Some value for this length scale, specified in parsec, must be supplied to the functions as the lpc parameter.

Note that the values provided by these functions do not match those from the paper Bailer-Jones et al. "Estimating Distances from Parallaxes IV: Distances to 1.33 Billion stars in Gaia Data Release 2", accepted for AJ (2018) arXiv:1804.10121. The calculations of that paper differ from the ones presented here in several ways: it uses a galactic model for the direction-dependent length scale not currently available here, it pre-applies a parallax correction of -0.029mas, and it uses different uncertainty measures and in some cases (bimodal PDF) a different best distance estimator.

Epoch Propagation

The Gaia source catalogue provides, for at least some sources, the six-parameter astrometric solution (Right Ascension, Declination, Parallax, Proper motion in RA and Dec, and Radial Velocity), along with errors on these values and correlations between these errors. While a crude estimate of the position at an earlier or later epoch than that of the measurement can be made by multiplying the proper motion components by epoch difference and adding to the measured position, a more careful treatment is required for accurate propagation between epochs of the astrometric parameters, and if required their errors and correlations. The expressions for this are set out in section 1.5.5 (Volume 1) of The Hipparcos and Tycho Catalogues, ESA SP-1200 (1997) (but see below), and the code is based on an implementation by Alexey Butkevich and Daniel Michalik (DPAC). A correction is applied to the SP-1200 treatment of radial velocity uncertainty following Michalik et al. 2014 2014A&A...571A..85M because of their better handling of small radial velocities or parallaxes.

The calculations give the same results, though not exactly in the same form, as the epoch propagation functions available in the Gaia archive service.

polarXYZ( phi, theta, r )
Converts from spherical polar to Cartesian coordinates.

• Parameters:
• phi (floating point): longitude in degrees
• theta (floating point): latitude in degrees
• r (floating point): radial distance
• Return value
• (array of floating point): 3-element vector giving Cartesian coordinates
• Examples:
• polarXYZ(ra, dec, distance_estimate)
• polarXYZ(l, b, 3262./parallax) - calculates vector components in units of light year in the galactic system, on the assumption that distance is the inverse of parallax

astromXYZ( ra, dec, parallax )
Calculates Cartesian components of position from RA, Declination and parallax. This is a convenience function, equivalent to:
    polarXYZ(ra, dec, 1000./parallax)


Note that this performs distance scaling using a simple inversion of parallax, which is not in general reliable for parallaxes with non-negligable errors. Use at your own risk.

• Parameters:
• ra (floating point): Right Ascension in degrees
• dec (floating point): Declination in degrees
• parallax (floating point): parallax in mas
• Return value
• (array of floating point): 3-element vector giving equatorial space coordinates in parsec
• Examples:
• astromXYZ(ra, dec, parallax)
• icrsToGal(astromXYZ(ra, dec, parallax))

icrsToGal( xyz )
Converts a 3-element vector representing ICRS (equatorial) coordinates to galactic coordinates. This can be used with position or velocity vectors.

The input vector is multiplied by the matrix AG', given in Eq. 3.61 of the Gaia DR2 documentation, following Eq. 1.5.13 of the Hipparcos catalogue.

The output coordinate system is right-handed, with the three components positive in the directions of the Galactic center, Galactic rotation, and the North Galactic Pole respectively.

• Parameters:
• xyz (array of floating point): 3-element vector giving ICRS Cartesian components
• Return value
• (array of floating point): 3-element vector giving Galactic Cartesian components
• Example:
• icrsToGal(polarXYZ(ra, dec, distance))

galToIcrs( xyz )
Converts a 3-element vector representing galactic coordinates to ICRS (equatorial) coordinates. This can be used with position or velocity vectors.

The input vector is multiplied by the matrix AG, given in Eq. 3.61 of the Gaia DR2 documentation, following Eq. 1.5.13 of the Hipparcos catalogue.

The input coordinate system is right-handed, with the three components positive in the directions of the Galactic center, Galactic rotation, and the North Galactic Pole respectively.

• Parameters:
• xyz (array of floating point): 3-element vector giving Galactic Cartesian components
• Return value
• (array of floating point): 3-element vector giving ICRS Cartesian components
• Example:
• galToIcrs(polarXYZ(l, b, distance))

icrsToEcl( xyz )
Converts a 3-element vector representing ICRS (equatorial) coordinates to ecliptic coordinates. This can be used with position or velocity vectors.

The transformation corresponds to that between the coordinates (ra,dec) and (ecl_lon,ecl_lat) in the Gaia source catalogue (DR2).

• Parameters:
• xyz (array of floating point): 3-element vector giving ICRS Cartesian components
• Return value
• (array of floating point): 3-element vector giving ecliptic Cartesian components
• Example:
• icrsToEcl(polarXYZ(ra, dec, distance))

eclToIcrs( xyz )
Converts a 3-element vector representing ecliptic coordinates to ICRS (equatorial) coordinates. This can be used with position or velocity vectors.

The transformation corresponds to that between the coordinates (ecl_lon,ecl_lat) and (ra,dec) in the Gaia source catalogue (DR2).

• Parameters:
• xyz (array of floating point): 3-element vector giving ecliptic Cartesian coordinates
• Return value
• (array of floating point): 3-element vector giving ICRS Cartesian coordinates
• Example:
• eclToIcrs(polarXYZ(ecl_lon, ecl_lat, distance))

astromUVW( astrom6 )
Calculates Cartesian components of velocity from quantities available in the Gaia source catalogue. The output is in the same coordinate system as the inputs, that is ICRS for the correspondingly-named Gaia quantities.

The input astrometry parameters are represented by a 6-element array, with the following elements:

 index  gaia_source name  unit    description
-----  ----------------  ----    -----------
0:   ra                deg     right ascension
1:   dec               deg     declination
2:   parallax          mas     parallax
3:   pmra              mas/yr  proper motion in ra * cos(dec)
4:   pmdec             mas/yr  proper motion in dec

The units used by this function are the units used in the gaia_source table.

This convenience function just invokes the 7-argument astromUVW function using the inverted parallax for the radial distance, and without invoking the Doppler correction. It is exactly equivalent to:

    astromUVW(a[0], a[1], a[3], a[4], a[5], 1000./a[2], false)

Note this naive inversion of parallax to estimate distance is not in general reliable for parallaxes with non-negligable errors.

• Parameters:
• astrom6 (array of floating point): vector of 6 astrometric parameters as provided by the Gaia source catalogue
• Return value
• (array of floating point): 3-element vector giving equatorial velocity components in km/s
• Examples:
• astromUVW(array(ra, dec, parallax, pmra, pmdec, radial_velocity))
• icrsToGal(astromUVW(array(ra, dec, parallax, pmra, pmdec, radial_velocity)))

astromUVW( ra, dec, pmra, pmdec, radial_velocity, r_parsec, useDoppler )
Calculates Cartesian components of velocity from the observed position and proper motion, radial velocity and radial distance, with optional light-time correction. The output is in the same coordinate system as the inputs, that is ICRS for the correspondingly-named Gaia quantities.

The radial distance must be supplied using the r_parsec parameter. A naive estimate from quantities in the Gaia source catalogue may be made with the expression 1000./parallax, though note that this simple inversion of parallax is not in general reliable for parallaxes with non-negligable errors.

The calculations are fairly straightforward, following Eq. 1.5.74 from the Hipparcos catalogue. A (usually small) Doppler factor accounting for light-time effects can also optionally be applied. The effect of this is to multiply the returned vector by a factor of 1/(1-radial_velocity/c), as discussed in Eq. 1.2.21 of the Hipparcos catalogue.

• Parameters:
• ra (floating point): Right Ascension in degrees
• dec (floating point): Declination in degrees
• pmra (floating point): proper motion in RA * cos(dec) in mas/yr
• pmdec (floating point): proper motion in declination in mas/yr
• radial_velocity (floating point): radial velocity in km/s
• r_parsec (floating point): radial distance in parsec
• useDoppler (boolean): whether to apply the Doppler factor to account for light-time effects
• Return value
• (array of floating point): 3-element vector giving equatorial velocity components in km/s
• Examples:
• astromUVW(ra, dec, pmra, pmdec, radial_velocity, dist, true)
• icrsToGal(astromUVW(ra, dec, pmra, pmdec, radial_velocity, 1000./parallax, false))

epochProp( tYr, astrom6 )
Propagates the astrometry parameters, supplied as a 6-element array, to a different epoch.

The input and output astrometry parameters are each represented by a 6-element array, with the following elements:

 index  gaia_source name  unit    description
-----  ----------------  ----    -----------
0:   ra                deg     right ascension
1:   dec               deg     declination
2:   parallax          mas     parallax
3:   pmra              mas/yr  proper motion in ra * cos(dec)
4:   pmdec             mas/yr  proper motion in dec

The units used by this function are the units used in the gaia_source table.

• Parameters:
• tYr (floating point): epoch difference in years
• astrom6 (array of floating point): astrometry at time t0, represented by a 6-element array as above (a 5-element array is also permitted where radial velocity is zero or unknown)
• Return value
• (array of floating point): astrometry at time t0+tYr, represented by a 6-element array as above
• Example:
• epochProp(-15.5, array(ra,dec,parallax,pmra,pmdec,radial_velocity)) - calculates the astrometry at 2000.0 of gaia_source values that were observed at 2015.5

epochPropErr( tYr, astrom22 )
Propagates the astrometry parameters and their associated errors and correlations, supplied as a 22-element array, to a different epoch.

The input and output astrometry parameters with associated error and correlation information are each represented by a 22-element array, with the following elements:

 index  gaia_source name      unit    description
-----  ----------------      ----    -----------
0:   ra                    deg     right ascension
1:   dec                   deg     declination
2:   parallax              mas     parallax
3:   pmra                  mas/yr  proper motion in RA * cos(dec)
4:   pmdec                 mas/yr  proper motion in Declination
6:   ra_error              mas     error in right ascension
7:   dec_error             mas     error in declination
8:   parallax_error        mas     error in parallax
9:   pmra_error            mas/yr  error in RA proper motion * cos(dec)
10:   pmdec_error           mas/yr  error in Declination proper motion
12:   ra_dec_corr                   correlation between ra and dec
13:   ra_parallax_corr              correlation between ra and parallax
14:   ra_pmra_corr                  correlation between ra and pmra
15:   ra_pmdec_corr                 correlation between ra and pmdec
16:   dec_parallax_corr             correlation between dec and parallax
17:   dec_pmra_corr                 correlation between dec and pmra
18:   dec_pmdec_corr                correlation between dec and pmdec
19:   parallax_pmra_corr            correlation between parallax and pmra
20:   parallax_pmdec_corr           correlation between parallax and pmdec
21:   pmra_pmdec_corr               correlation between pmra and pmdec

Note the correlation coefficients, always in the range -1..1, are dimensionless.

This is clearly an unwieldy function to invoke, but if you are using it with the gaia_source catalogue itself, or other similar catalogues with the same column names and units, you can invoke it by just copying and pasting the example shown in this documentation.

This transformation is only applicable for radial velocities determined independently of the astrometry, such as those obtained with a spectrometer. It is not applicable for the back-transformation of data already propagated to another epoch.

• Parameters:
• tYr (floating point): epoch difference in years
• astrom22 (array of floating point): astrometry at time t0, represented by a 22-element array as above
• Return value
• (array of floating point): astrometry at time t0+tYr, represented by a 22-element array as above
• Example:
• epochPropErr(-15.5, array( ra,dec,parallax,pmra,pmdec,radial_velocity, ra_error,dec_error,parallax_error,pmra_error,pmdec_error,radial_velocity_error, ra_dec_corr,ra_parallax_corr,ra_pmra_corr,ra_pmdec_corr, dec_parallax_corr,dec_pmra_corr,dec_pmdec_corr, parallax_pmra_corr,parallax_pmdec_corr, pmra_pmdec_corr)) - calculates the astrometry with all errors and correlations at 2000.0 for gaia_source values that were observed at 2015.5.

rvMasyrToKms( rvMasyr, plxMas )
Converts from normalised radial velocity in mas/year to unnormalised radial velocity in km/s.

The output is calculated as AU_YRKMS * rvMasyr / plxMas, where AU_YRKMS=4.740470446 is one Astronomical Unit in km.yr/sec.

• Parameters:
• rvMasyr (floating point): normalised radial velocity, in mas/year
• plxMas (floating point): parallax in mas
• Return value
• (floating point): radial velocity in km/s

rvKmsToMasyr( rvKms, plxMas )
Converts from unnormalised radial velocity in km/s to normalised radial velocity in mas/year.

The output is calculated as rvKms * plxMas / AU_YRKMS, where AU_YRKMS=4.740470446 is one Astronomical Unit in km.yr/sec.

• Parameters:
• rvKms (floating point): unnormalised radial velocity, in mas/year
• plxMas (floating point): parallax in mas
• Return value
• (floating point): radial velocity in mas/year

distanceEstimateEdsd( plxMas, plxErrorMas, lPc )
Best estimate of distance using the Exponentially Decreasing Space Density prior. This estimate is provided by the mode of the PDF.

• Parameters:
• plxMas (floating point): parallax in mas
• plxErrorMas (floating point): parallax error in mas
• lPc (floating point): length scale in parsec
• Return value
• (floating point): best distance estimate in parsec

distanceBoundsEdsd( plxMas, plxErrorMas, lPc )
Calculates the 5th and 95th percentile confidence intervals on the distance estimate using the Exponentially Decreasing Space Density prior.

Note this function has to numerically integrate the PDF to determine quantile values, so it is relatively slow.

• Parameters:
• plxMas (floating point): parallax in mas
• plxErrorMas (floating point): parallax error in mas
• lPc (floating point): length scale in parsec
• Return value
• (array of floating point): 2-element array giving the 5th and 95th percentiles in parsec of the EDSD distance PDF

distanceQuantilesEdsd( plxMas, plxErrorMas, lPc, qpoints, ... )
Calculates arbitrary quantiles for the distance estimate using the Exponentially Decreasing Space Density prior.

Note this function has to numerically integrate the PDF to determine quantile values, so it is relatively slow.

• Parameters:
• plxMas (floating point): parallax in mas
• plxErrorMas (floating point): parallax error in mas
• lPc (floating point): length scale in parsec
• qpoints (floating point, one or more): one or more required quantile cut points, each in the range 0..1
• Return value
• (array of floating point): array with one element for each of the supplied qpoints giving the corresponding distance in parsec
• Examples:
• distanceQuantilesEdsd(parallax, parallax_error, 1350, 0.5)[0] calculates the median of the EDSD distance PDF using a length scale of 1.35kpc
• distanceQuantilesEdsd(parallax, parallax_error, 3000, 0.01, 0.99) returns a 2-element array giving the 1st and 99th percentile of the distance estimate using a length scale of 3kpc

distanceToModulus( distPc )
Converts a distance in parsec to a distance modulus. The formula is 5*log10(distPc)-5.

• Parameters:
• distPc (floating point): distance in parsec
• Return value
• (floating point): distance modulus in magnitudes

modulusToDistance( distmod )
Converts a distance modulus to a distance in parsec. The formula is 10^(1+distmod/5).

• Parameters:
• distmod (floating point): distance modulus in magnitudes
• Return value
• (floating point): distance in parsec

AU_YRKMS
This quantity is A_v, the Astronomical Unit expressed in km.yr/sec. See the Hipparcos catalogue (ESA SP-1200) table 1.2.2 and Eq. 1.5.24.

PC_AU
Parsec in Astronomical Units, equal to 648000/PI.

PC_YRKMS
Parsec in units of km.yr/sec.

C_KMS
The speed of light in km/s (exact).

#### 10.6.12 KCorrections

Functions for calculating K-corrections.

kCorr( filter, redshift, colorType, colorValue )
Calculates K-corrections. This allows you to determine K-corrections for a galaxy, given its redshift and a colour. Filters for GALEX, SDSS, UKIDSS, Johnson, Cousins and 2MASS are covered.

To define the calculation you must choose both a filter, specified as a KCF_* constant, and a colour (filter pair) specified as a KCC_* constant. For each available filter, only certain colours are available, as described in the documentation of the relevant KCF_* constant.

The algorithm used is described at http://kcor.sai.msu.ru/. This is based on the paper "Analytical Approximations of K-corrections in Optical and Near-Infrared Bands" by I.Chilingarian, A.-L.Melchior and I.Zolotukhin (2010MNRAS.405.1409C), but extende