# STILTS - Starlink Tables Infrastructure Library Tool SetVersion 3.4

Mark Taylor
11 January 2021

## 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 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 and server.
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:

• 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
• tjoin
• tloop
• tmatch1
• tmatch2
• tmatchn
• tmulti
• tmultin
• tpipe
• tskymap
• tskymatch2
• votcopy
• votlint

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>]

calc
cdsskymatch
cone
coneskymatch
funcs
pixfoot
pixsample
plot2d
plot3d
plothist
regquery
server
sqlclient
sqlskymatch
sqlupdate
taplint
tapquery
tapresume
tapskymatch
tcat
tcatn
tcopy
tcube
tjoin
tloop
tmatch1
tmatch2
tmatchn
tmulti
tmultin
tpipe
tskymap
tskymatch2
votcopy
votlint
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 is usually only done if the -disk flag has been specified (see Section 2.1).
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, on versions 2.5.0 and 2.5.1; it's recommended to use the latest version if you don't have some reason to use one of the others. 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
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 and doesn't start with a minus character ('-'). 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:

Column Name
The name of a column may be used if it contains no spaces and doesn't start with a minus character ('-'). 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. 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. 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 count Usage:  omode=count  Counts the number of rows and columns and writes the result to standard output. #### 6.4.3 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.4 gui Usage:  omode=gui  Displays the table in a scrollable window. #### 6.4.5 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.6 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.7 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.8 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.9 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.10 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.11 tosql Usage:  omode=tosql protocol=<jdbc-protocol> host=<value> db=<db-name> dbtable=<table-name> write=create|dropcreate|append user=<username> password=<passwd>  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' values2='radiansToDegrees(RArad) radiansToDegrees(DECrad)'  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> <secondary-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.9.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 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  will produce an animated gif from the input frames. 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  You can pipe the output of tloop (or any other command) as the animation table on the unix command line by specifying animate=- (the "-" character stands for standard input). Note however that in this case you must explicitly give the file format (using the afmt parameter) and it must be a format which STILTS is capable of streaming (VOTable is suitable; ASCII is not). A common requirement is to produce an animation of rotating a 3-d plot. Here's an example of how to do it from a unix shell:  stilts tloop phi 15 375 2 ofmt=votable \ | stilts plot2sphere layer_1=mark in_1=hip_main.fits lon_1=radeg lat_1=dedeg r_1=plx \ animate=- afmt=votable  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|... (MarkShape) 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|... (MarkShape) 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|... 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|... (XYShape) 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] 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|... 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 xmin=9 xmax=11 ymin=12 ymax=13.5 arrowN = small_arrow|medium_arrow|... (ErrorRenderer) 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] 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|... 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 layer2=xyerror xerrhi2=e_S500 yerrhi2=e_S160 errorbar2=capped_lines xlog=true ylog=true xmin=0.012 xmax=1 ymin=0.01 ymax=10 errorbarN = none|lines|capped_lines|... (ErrorRenderer) 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] 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|... 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|... (ErrorRenderer) 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] 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|... 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|... (ErrorRenderer) 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] 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 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] #### 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|... (MarkShape) 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|fill|cross|star fastN=true|false 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 fastN = true|false (Boolean) Determines whether speed is favoured over accuracy when drawing polygons. In some cases setting this false will give visually better results, and in some cases setting it true will speed up plotting. In other cases, the setting will make no difference to either. It may be necessary to set it false when filling polygons that may be re-entrant. [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] minshapeN = filled_circle|open_circle|... (MarkShape) 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|fill|cross|star (PolygonMode) 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 • 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] #### 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|... (MarkShape) 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|fill|cross|star fastN=true|false 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 fastN = true|false (Boolean) Determines whether speed is favoured over accuracy when drawing polygons. In some cases setting this false will give visually better results, and in some cases setting it true will speed up plotting. In other cases, the setting will make no difference to either. It may be necessary to set it false when filling polygons that may be re-entrant. [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] 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 algebraic expression based on column names as described in Section 10. polymodeN = outline|fill|cross|star (PolygonMode) 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 • 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] 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|fill|cross|star fastN=true|false 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 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 fast_pf=false 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 (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. If left blank, a guess will be taken depending on the data type of the value supplied for the areaN value. fastN = true|false (Boolean) Determines whether speed is favoured over accuracy when drawing polygons. In some cases setting this false will give visually better results, and in some cases setting it true will speed up plotting. In other cases, the setting will make no difference to either. It may be necessary to set it false when filling polygons that may be re-entrant. [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] minshapeN = filled_circle|open_circle|... (MarkShape) 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|fill|cross|star (PolygonMode) 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 • 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] #### 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 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 fast1=false 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 (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. 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|... (MarkShape) 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 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.16 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.17 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|... 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] #### 8.3.18 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|... spacingN=<pixels> crowdlimitN=<n> areaN=<area-expr> areatypeN=STC-S|POLYGON|CIRCLE|POINT|MOC-ASCII 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 fast_1=false 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 (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. 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] #### 8.3.19 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 of the combined values (may be slow) • 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.20 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 of the combined values (may be slow) • 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.21 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.22 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. 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 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, there is a y value calculated for each pixel column, and if false, there is an x value 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] 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.23 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=true|false 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 of the combined values (may be slow) • 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 = true|false (Boolean) If true, the histogram bars plotted are calculated cumulatively; each bin includes the counts from all previous bins. Note that setting cumulative true may not make much sense with some other parameter values, for instance averaging aggregation modes. [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] 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.24 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=true|false 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 of the combined values (may be slow) • 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 = true|false (Boolean) If true, the histogram bars plotted are calculated cumulatively; each bin includes the counts from all previous bins. Note that setting cumulative true may not make much sense with some other parameter values, for instance averaging aggregation modes. [Default: false] 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.25 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=true|false 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 = true|false (Boolean) If true, the histogram bars plotted are calculated cumulatively; each bin includes the counts from all previous bins. Note that setting cumulative true may not make much sense with some other parameter values, for instance averaging aggregation modes. [Default: false] 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.26 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=true|false 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 = true|false (Boolean) If true, the histogram bars plotted are calculated cumulatively; each bin includes the counts from all previous bins. Note that setting cumulative true may not make much sense with some other parameter values, for instance averaging aggregation modes. [Default: false] 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: inferno, magma, plasma, viridis, cividis, cubehelix, sron, rainbow, rainbow2, rainbow3, pastel, accent, gnuplot, gnuplot2, specxby, set1, paired, hotcold, rdbu, piyg, brbg, cyan-magenta, red-blue, brg, heat, cold, light, greyscale, colour, standard, bugn, bupu, orrd, pubu, purd, huecl, 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.27 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.28 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.29 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|... 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|... (ErrorRenderer) 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] 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.30 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|... 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|... (ErrorRenderer) 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] 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.31 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|... 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|... (ErrorRenderer) 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] 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.32 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 of the combined values (may be slow) • 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.33 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 of the combined values (may be slow) • 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.34 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=ecliptic layer1=skygrid gridsys1=galactic gridcolor1=HotPink labelpos1=none  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.35 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|... 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|... (ErrorRenderer) 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] 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.36 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|... 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|... (ErrorRenderer) 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] 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.37 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.38 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.39 yerror Shape Plots symmetric or asymmetric error bars in the Y direction. Shading Paints markers in a single fixed colour. Usage Overview:  layerN=yerror errorbarN=none|lines|capped_lines|caps|arrows colorN=<rrggbb>|red|blue|... 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 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] errorbarN = none|lines|capped_lines|caps|arrows (ErrorRenderer) 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] 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. 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.40 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 algebraic expression based on column names as described in Section 10. 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: blacker, whiter, inferno, magma, plasma, viridis, cividis, cubehelix, sron, rainbow, rainbow2, rainbow3, pastel, accent, gnuplot, gnuplot2, specxby, set1, paired, hotcold, rdbu, piyg, brbg, cyan-magenta, red-blue, brg, heat, cold, light, greyscale, colour, standard, bugn, bupu, orrd, pubu, purd, huecl, 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|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|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 of the combined values (may be slow) • 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). ## 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.14.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.

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
Evaluates to a double-precision random number 0<=x<1 with a value which is fixed for a given row in this expression. The quality of the random numbers may not be particularly good. The deprecated alias "RANDOM" may also be used.

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. ### 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" add( array1, array2 ) Returns the result of adding two numeric arrays element by element. Both arrays must be numeric, and the arrays must have the same length. If either of those conditions is not true, null is returned. The types of the arrays do not need to be the same, so for example it is permitted to add an integer array to a floating point array. • Parameters: • array1 (Object): first array of numeric values • array2 (Object): second array of numeric values • Return value • (array of floating point): element-by-element sum of array1 and array2, the same length as the input arrays • Example: • add(array(1,2,3), array(0.1,0.2,0.3)) = [1.1, 2.2, 3.3] add( array, constant ) Returns the result of adding a constant value to every element of a numeric array. If the supplied array argument is not a numeric array, null is returned. • Parameters: • array (Object): array input • constant (floating point): value to add to each array element • Return value • (array of floating point): array output, the same length as the array parameter • Example: • add(array(1,2,3), 10) = [11,12,13] subtract( array1, array2 ) Returns the result of subtracting one numeric array from the other element by element. Both arrays must be numeric, and the arrays must have the same length. If either of those conditions is not true, null is returned. The types of the arrays do not need to be the same, so for example it is permitted to subtract an integer array from a floating point array. • Parameters: • array1 (Object): first array of numeric values • array2 (Object): second array of numeric values • Return value • (array of floating point): element-by-element difference of array1 and array2, the same length as the input arrays • Example: • subtract(array(1,2,3), array(0.1,0.2,0.3)) = [0.9, 1.8, 2.7] multiply( array1, array2 ) Returns the result of multiplying two numeric arrays element by element. Both arrays must be numeric, and the arrays must have the same length. If either of those conditions is not true, null is returned. The types of the arrays do not need to be the same, so for example it is permitted to multiply an integer array by a floating point array. • Parameters: • array1 (Object): first array of numeric values • array2 (Object): second array of numeric values • Return value • (array of floating point): element-by-element product of array1 and array2, the same length as the input arrays • Example: • multiply(array(1,2,3), array(2,4,6)) = [2, 8, 18] multiply( array, constant ) Returns the result of multiplying every element of a numeric array by a constant value. If the supplied array argument is not a numeric array, null is returned. • Parameters: • array (Object): array input • constant (floating point): value by which to multiply each array element • Return value • (array of floating point): array output, the same length as the array parameter • Example: • multiply(array(1,2,3), 2) = [2, 4, 6] divide( array1, array2 ) Returns the result of dividing two numeric arrays element by element. Both arrays must be numeric, and the arrays must have the same length. If either of those conditions is not true, null is returned. The types of the arrays do not need to be the same, so for example it is permitted to divide an integer array by a floating point array. • Parameters: • array1 (Object): array of numerator values (numeric) • array2 (Object): array of denominator values (numeric) • Return value • (array of floating point): element-by-element result of array1[i]/array2[i] the same length as the input arrays • Example: • divide(array(0,9,4), array(1,3,8)) = [0, 3, 0.5] 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] 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] 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 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 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.4 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 #### 10.6.5 CoordsRadians 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 ) Converts hours to radians. • Parameters: • hours (floating point): angle in hours • Return value • (floating point): angle in radians degreesToRadians( deg ) Converts degrees to radians. • Parameters: • deg (floating point): angle in degrees • Return value • (floating point): angle in radians radiansToDegrees( rad ) Converts radians to degrees. • 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.6 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.7 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.8 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.9 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.10 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)) uvw_gal = icrsToGal(astromUVW(array(ra,dec,parallax,pmra,pmdec,radial_velocity)))  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 5: radial_velocity km/s barycentric radial velocity  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. Note that no attempt is made to adjust for solar motion. • 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 5: radial_velocity km/s barycentric radial velocity  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 5: radial_velocity km/s barycentric radial velocity 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 11: radial_velocity_error km/s error in barycentric radial velocity 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.11 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 extended to include GALEX UV bands and with redshift coverage up to 0.5 as described in "Universal UV-optical Colour-Colour-Magnitude Relation of Galaxies" by I.Chilingarian and I.Zolotukhin (2012MNRAS.419.1727C). • Parameters: • filter (KCorrections.KFilter): KCF_* constant defining the filter for which you want to calculate the K-correction • redshift (floating point): galaxy redshift; this should be in the range 0-0.5 • colorType (KCorrections.KColor): KCC_* constant defining the filter pair for the calculation; check the KCF_* constant documentation to see which ones are permitted for a given filter • colorValue (floating point): the value of the colour • Return value • (floating point): K correction • Examples: • kCorr(KCF_g, 0.16, KCC_gr, -0.8) = 3.593 • kCorr(KCF_FUV, 0.48, KCC_FUVu, 0.31) = -0.170 KCF_FUV GALEX FUV filter (AB). Use with KCC_FUVNUV or KCC_FUVu. KCF_NUV GALEX NUV filter (AB). Use with KCC_NUVg or KCC_NUVr. KCF_u SDSS u filter (AB). Use with KCC_ur, KCC_ui or KCC_uz. KCF_g SDSS g filter (AB). Use with KCC_gr, KCC_gi or KCC_gz. KCF_r SDSS r filter (AB). Use with KCC_gr or KCC_ur. KCF_i SDSS i filter (AB). Use with KCC_gi or KCC_ui. KCF_z SDSS z filter (AB). Use with KCC_rz, KCC_gz or KCC_uz. KCF_Y UKIDSS Y filter (AB). Use with KCC_YH or KCC_YK. KCF_J UKIDSS J filter (AB). Use with KCC_JK or KCC_JH. KCF_H UKIDSS H filter (AB). Use with KCC_HK or KCC_JH. KCF_K UKIDSS K filter (AB). Use with KCC_JK or KCC_HK. KCF_U Johnson U filter (Vega). Use with KCC_URc. KCF_B Johnson B filter (Vega). Use with KCC_BRc or KCC_BIc. KCF_V Johnson V filter (Vega). Use with KCC_VIc or KCC_VRc. KCF_Rc Cousins Rc filter (Vega). Use with KCC_BRc or KCC_VRc. KCF_Ic Cousins Ic filter (Vega). Use with KCC_VIc. KCF_J2 2MASS J filter (Vega). Use with KCC_J2Ks2 or KCC_J2H2. KCF_H2 2MASS H filter (Vega). Use with KCC_H2Ks2 or KCC_J2H2. KCF_Ks2 2MASS Ks filter (Vega). Use with KCC_J2Ks2 or KCC_H2Ks2. KCC_BIc Johnson B - Cousins Ic colour. KCC_BRc Johnson B - Cousins Rc colour. KCC_FUVNUV GALEX FUV - NUV colour. KCC_FUVu GALEX FUV - SDSS u colour. KCC_gi SDSS g - i colour. KCC_gr SDSS g - r colour. KCC_gz SDSS g - z colour. KCC_H2Ks2 2MASS H - Ks colour. KCC_HK UKIDSS H - K colour. KCC_J2H2 2MASS J - H colour. KCC_J2Ks2 2MASS J - Ks colour. KCC_JH UKIDSS J - H colour. KCC_JK UKIDSS J - K colour. KCC_NUVg GALEX NUV - SDSS g colour. KCC_NUVr GALEX NUV - SDSS r colour. KCC_rz SDSS r - SDSS z colour. KCC_ui SDSS u - SDSS i colour. KCC_URc Johnson U - Cousins Rc colour. KCC_ur SDSS u - r colour. KCC_uz SDSS u - z colour. KCC_VIc Johnson V - Cousins Ic colour. KCC_VRc Johnson V - Cousins Rc colour. KCC_YH UKIDSS Y - H colour. KCC_YK UKIDSS Y - K colour. #### 10.6.12 Lists Functions which operate on lists of values. Some of these resemble similar functions in the Arrays class, and in some cases are interchangeable, but these are easier to use on non-array values because you don't have to explicitly wrap up lists of arguments as an array. However, for implementation reasons, most of the functions defined here can be used on values which are already double[] arrays (for instance array-valued columns) rather than as comma-separated lists of floating point values. sum( values, ... ) Returns the sum of all the non-blank supplied arguments. • Parameters: • values (floating point, one or more): one or more numeric values • Return value • (floating point): sum of values • Examples: • sum(1, 3, 99) = 103 • sum(1, 3, NaN) = 4 mean( values, ... ) Returns the mean of all the non-blank supplied arguments. • Parameters: • values (floating point, one or more): one or more numeric values • Return value • (floating point): mean of values • Examples: • mean(2, 4, 6, 8) = 5 • mean(100.5, 99.5, NaN) = 100 variance( values, ... ) Returns the population variance of the non-blank supplied arguments. • Parameters: • values (floating point, one or more): one or more numeric values • Return value • (floating point): population variance of values • Examples: • variance(0, 3, 4, 3, 0) = 2.8 • variance(0, 3, NaN, 3, NaN) = 2 stdev( values, ... ) Returns the population standard deviation of the non-blank supplied arguments. • Parameters: • values (floating point, one or more): one or more numeric values • Return value • (floating point): population standard deviation of values • Example: • stdev(-3, -2, 0, 0, 1, 2, 3, 4, 5, 6) = 2.8 min( values, ... ) Returns the minimum of all the non-blank supplied arguments. • Parameters: • values (floating point, one or more): one or more numeric values • Return value • (floating point): minimum of values • Example: • min(20, 25, -50, NaN, 101) = -50 max( values, ... ) Returns the maximum of all the non-blank supplied arguments. • Parameters: • values (floating point, one or more): one or more numeric values • Return value • (floating point): maximum of values • Example: • max(20, 25, -50, NaN, 101) = 101 median( values, ... ) Returns the median of all the non-blank supplied arguments. • Parameters: • values (floating point, one or more): one or more numeric values • Return value • (floating point): median of values • Example: • median(-100000, 5, 6, 7, 8) = 6 countTrue( values, ... ) Returns the number of true values in a list of boolean arguments. Note if any of the values are blank, the result may be blank as well. • Parameters: • values (boolean, one or more): one or more true/false values • Return value • (integer): number of elements of values that are true • Example: • countTrue(false, false, true, false, true) = 2 #### 10.6.13 Maths Standard mathematical and trigonometric functions. Trigonometric functions work with angles in radians. sin( theta ) Sine of an angle. • Parameters: • theta (floating point): an angle, in radians. • Return value • (floating point): the sine of the argument. cos( theta ) Cosine of an angle. • Parameters: • theta (floating point): an angle, in radians. • Return value • (floating point): the cosine of the argument. tan( theta ) Tangent of an angle. • Parameters: • theta (floating point): an angle, in radians. • Return value • (floating point): the tangent of the argument. asin( x ) Arc sine of an angle. The result is in the range of -pi/2 through pi/2. • Parameters: • x (floating point): the value whose arc sine is to be returned. • Return value • (floating point): the arc sine of the argument (radians) acos( x ) Arc cosine of an angle. The result is in the range of 0.0 through pi. • Parameters: • x (floating point): the value whose arc cosine is to be returned. • Return value • (floating point): the arc cosine of the argument (radians) atan( x ) Arc tangent of an angle. The result is in the range of -pi/2 through pi/2. • Parameters: • x (floating point): the value whose arc tangent is to be returned. • Return value • (floating point): the arc tangent of the argument (radians) ln( x ) Natural logarithm. • Parameters: • x (floating point): argument • Return value • (floating point): loge(x) exp( x ) Euler's number e raised to a power. • Parameters: • x (floating point): the exponent to raise e to. • Return value • (floating point): the value ex, where e is the base of the natural logarithms. log10( x ) Logarithm to base 10. • Parameters: • x (floating point): argument • Return value • (floating point): log10(x) exp10( x ) Power of 10. This convenience function is identical to pow(10,x). • Parameters: • x (floating point): argument • Return value • (floating point): 10x sqrt( x ) Square root. The result is correctly rounded and positive. • Parameters: • x (floating point): a value. • Return value • (floating point): the positive square root of x. If the argument is NaN or less than zero, the result is NaN. square( x ) Raise to the power 2. • Parameters: • x (floating point): a value • Return value • (floating point): x * x hypot( xs, ... ) Returns the square root of the sum of squares of its arguments. In the 2-argument case, doing it like this may avoid intermediate overflow or underflow. • Parameters: • xs (floating point, one or more): one or more numeric values • Return value • (floating point): sqare root of sum of squares of arguments • Examples: • hypot(3,4) = 5 • hypot(2,2,2,2) = 4 atan2( y, x ) Converts rectangular coordinates (x,y) to polar (r,theta). This method computes the phase theta by computing an arc tangent of y/x in the range of -pi to pi. • Parameters: • y (floating point): the ordinate coordinate • x (floating point): the abscissa coordinate • Return value • (floating point): the theta component (radians) of the point (r,theta) in polar coordinates that corresponds to the point (x,y) in Cartesian coordinates. pow( a, b ) Exponentiation. The result is the value of the first argument raised to the power of the second argument. • Parameters: • a (floating point): the base. • b (floating point): the exponent. • Return value • (floating point): the value ab. sinh( x ) Hyperbolic sine. • Parameters: • x (floating point): parameter • Return value • (floating point): result cosh( x ) Hyperbolic cosine. • Parameters: • x (floating point): parameter • Return value • (floating point): result tanh( x ) Hyperbolic tangent. • Parameters: • x (floating point): parameter • Return value • (floating point): result asinh( x ) Inverse hyperbolic sine. • Parameters: • x (floating point): parameter • Return value • (floating point): result acosh( x ) Inverse hyperbolic cosine. • Parameters: • x (floating point): parameter • Return value • (floating point): result atanh( x ) Inverse hyperbolic tangent. • Parameters: • x (floating point): parameter • Return value • (floating point): result E Euler's number e, the base of natural logarithms. PI Pi, the ratio of the circumference of a circle to its diameter. Infinity Positive infinite floating point value. NaN Not-a-Number floating point value. Use with care; arithmetic and logical operations behave in strange ways near NaN (for instance, NaN!=NaN). For most purposes this is equivalent to the blank value. RANDOM Evaluates to a random number in the range 0<=x<1. This is different for each cell of the table. The quality of the randomness may not be particularly good. #### 10.6.14 Shapes Functions useful for working with shapes in the (X, Y) plane. polyLine( x, xys, ... ) Function of x defined by straight line segments between a specified list of vertices. The vertices are specified as a sequence of Xi, Yi pairs, for which the Xi values must be monotonic. The line segment at each end of the specified point sequence is considered to be extended to infinity. If only two points are specified, this is the equation of a straight line between those points. As a special case, if only one point is specified, the line is considered to be a horizontal line (equal to the sole specified Yi coordinate for all x). By reversing the Xi and Yi values, this function can equally be used to represent a function X(y) rather than Y(x). If the number of coordinates is odd, or the Xi values are not monotonic, behaviour is undefined. • Parameters: • x (floating point): X value at which function is to be evaluated • xys (floating point, one or more): 2N arguments (x1, y1, x2, y2, ..., xN, yN) giving vertices of an N-point line with monotonically increasing or decreasing X values • Return value • (floating point): Y coordinate of poly-line for specified x • Example: • polyLine(5, 0,0, 2,2) = 5 isInside( x, y, xys, ... ) Indicates whether a given test point is inside a polygon defined by specified list of vertices. The vertices are specified as a sequence of Xi, Yi pairs. If the number of coordinates is odd, the behaviour is not defined. • Parameters: • x (floating point): X coordinate of test point • y (floating point): Y coordinate of test point • xys (floating point, one or more): 2N arguments (x1, y1, x2, y2, ..., xN, yN) giving vertices of an N-sided polygon • Return value • (boolean): true iff test point is inside, or on the border of, the polygon • Examples: • isInside(0.5,0.5, 0,0, 0,1, 1,1, 1,0) = true • isInside(0,0, array(10,20, 20,20, 20,10)) = false #### 10.6.15 Sky Functions useful for working with shapes on a sphere. All angles are expressed in degrees. skyDistance( lon1, lat1, lon2, lat2 ) Calculates the separation (distance around a great circle) of two points on the sky in degrees. This function is identical to skyDistanceDegrees in class CoordsDegrees. • Parameters: • lon1 (floating point): point 1 longitude in degrees • lat1 (floating point): point 1 latitude in degrees • lon2 (floating point): point 2 longitude in degrees • lat2 (floating point): point 2 latitude in degrees • Return value • (floating point): angular distance between point 1 and point 2 in degrees midLon( lon1, lon2 ) Determines the longitude mid-way between two given longitudes. In most cases this is just the mean of the two values, but this function copes correctly with the case where the given values straddle the lon=0 line. • Parameters: • lon1 (floating point): first longitude in degrees • lon2 (floating point): second longitude in degrees • Return value • (floating point): longitude midway between the given values • Examples: • midLon(204.0, 203.5) = 203.75 • midLon(2, 359) = 0.5 midLat( lat1, lat2 ) Determines the latitude midway between two given latitudes. This simply returns the mean of the two values, but is supplied for convenience to use alongside the midLon function. • Parameters: • lat1 (floating point): first latitude in degrees • lat2 (floating point): second latitude in degrees • Return value • (floating point): latitude midway between the given values • Example: • midLat(23.5, 24.0) = 23.75 inSkyPolygon( lon0, lat0, lonLats, ... ) Tests whether a given sky position is inside the polygon defined by a given set of vertices. The bounding lines of the polygon are the minor arcs of great circles between adjacent vertices, with an extra line assumed between the first and last supplied vertex. The interior of the polygon is defined to be the smaller of the two regions separated by the boundary. The vertices are specified as a sequence of loni, lati pairs. The implementation of this point-in-polygon function is mostly correct, but may not be bulletproof. It ought to work for relatively small regions anywhere on the sky, but for instance it may get the sense wrong for regions that extend to cover both poles. • Parameters: • lon0 (floating point): test point latitude in degrees • lat0 (floating point): test point longitude in degrees • lonLats (floating point, one or more): 2N arguments (lon1, lat1, lon2, lat2, ..., lonN, latN) giving (longitude, latitude) vertices of an N-sided polygon in degrees • Return value • (boolean): true iff test point is inside, or on the border of, the polygon #### 10.6.16 Strings String manipulation and query functions. concat( strings, ... ) Concatenates multiple values into a string. In some cases the same effect can be achieved by writing s1+s2+..., but this method makes sure that values are converted to strings, with the blank value invisible. • Parameters: • strings (Object, one or more): one or more strings • Return value • (String): concatenation of input strings, without separators • Examples: • concat("blue", "moon") = "bluemoon" • concat("1", 2, 3, "4") = "1234" • concat("Astro", null, "Physics") = "AstroPhysics" join( separator, words, ... ) Joins multiple values into a string, with a given separator between each pair. • Parameters: • separator (String): string to insert between adjacent words • words (Object, one or more): one or more values to join • Return value • (String): input values joined together with separator • Examples: • join("<->", "alpha", "beta", "gamma") = "alpha<->beta<->gamma" • join(" ", 1, "brown", "mouse") = "1 brown mouse" equals( s1, s2 ) Determines whether two strings are equal. Note you should use this function instead of s1==s2, which can (for technical reasons) return false even if the strings are the same. • Parameters: • s1 (String): first string • s2 (String): second string • Return value • (boolean): true if s1 and s2 are both blank, or have the same content equalsIgnoreCase( s1, s2 ) Determines whether two strings are equal apart from possible upper/lower case distinctions. • Parameters: • s1 (String): first string • s2 (String): second string • Return value • (boolean): true if s1 and s2 are both blank, or have the same content apart from case folding • Examples: • equalsIgnoreCase("Cygnus", "CYGNUS") = true • equalsIgnoreCase("Cygnus", "Andromeda") = false startsWith( whole, start ) Determines whether a string starts with a certain substring. • Parameters: • whole (String): the string to test • start (String): the sequence that may appear at the start of whole • Return value • (boolean): true if the first few characters of whole are the same as start • Example: • startsWith("CYGNUS X-1", "CYG") = true endsWith( whole, end ) Determines whether a string ends with a certain substring. • Parameters: • whole (String): the string to test • end (String): the sequence that may appear at the end of whole • Return value • (boolean): true if the last few characters of whole are the same as end • Example: • endsWith("M32", "32") = true contains( whole, sub ) Determines whether a string contains a given substring. • Parameters: • whole (String): the string to test • sub (String): the sequence that may appear within whole • Return value • (boolean): true if the sequence sub appears within whole • Example: • contains("Vizier", "izi") = true length( str ) Returns the length of a string in characters. • Parameters: • str (String): string • Return value • (integer): number of characters in str • Example: • length("M34") = 3 split( words ) Splits a string into an array of space-separated words. One or more spaces separates each word from the next. Leading and trailing spaces are ignored. The result is an array of strings, and if you want to use the individual elements you need to use square-bracket indexing, with [0] representing the first object • Parameters: • words (String): string with embedded spaces delimiting the words • Return value • (array of String): array of the separate words; you can extract the individual words from the result using square bracket indexing • Examples: • split("211:54:01 +29:33:41") gives a 2-element array, first element is "211:54:01" and second element is "+29:33:41". • split(" cat dog cow ")[1] = "dog" split( words, regex ) Splits a string into an array of words separated by a given regular expression. The result is an array of strings, and if you want to use the individual elements you need to use square-bracket indexing, with [0] representing the first object • Parameters: • words (String): string with multiple parts • regex (String): regular expression delimiting the different words in the words parameter • Return value • (array of String): array of the separate words; you can extract the individual words from the result using square bracket indexing • Examples: • split("cat, dog, cow", ", *") gives a 3-element string array. • split("23.0, 45.92", ", ")[0] = "23.0" • parseDouble(split("23.0, 45.92", ", ")[0]) = 23 matches( str, regex ) Tests whether a string matches a given regular expression. • Parameters: • str (String): string to test • regex (String): regular expression string • Return value • (boolean): true if regex matches str anywhere • Example: • matches("Hubble", "ub") = true matchGroup( str, regex ) Returns the first grouped expression matched in a string defined by a regular expression. A grouped expression is one enclosed in parentheses. • Parameters: • str (String): string to match against • regex (String): regular expression containing a grouped section • Return value • (String): contents of the matched group (or null, if regex didn't match str) • Example: • matchGroup("NGC28948b","NGC([0-9]*)") = "28948" replaceFirst( str, regex, replacement ) Replaces the first occurrence of a regular expression in a string with a different substring value. • Parameters: • str (String): string to manipulate • regex (String): regular expression to match in str • replacement (String): replacement string • Return value • (String): same as str, but with the first match (if any) of regex replaced by replacement • Example: • replaceFirst("Messier 61", "Messier ", "M-") = "M-61" replaceAll( str, regex, replacement ) Replaces all occurrences of a regular expression in a string with a different substring value. • Parameters: • str (String): string to manipulate • regex (String): regular expression to match in str • replacement (String): replacement string • Return value • (String): same as str, but with all matches of regex replaced by replacement • Example: • replaceAll("1-2--3---4","--*","x") = "1x2x3x4" substring( str, startIndex ) Returns the last part of a given string. The substring begins with the character at the specified index and extends to the end of this string. • Parameters: • str (String): the input string • startIndex (integer): the beginning index, inclusive • Return value • (String): last part of str, omitting the first startIndex characters • Example: • substring("Galaxy", 2) = "laxy" substring( str, startIndex, endIndex ) Returns a substring of a given string. The substring begins with the character at startIndex and continues to the character at index endIndex-1 Thus the length of the substring is endIndex-startIndex. • Parameters: • str (String): the input string • startIndex (integer): the beginning index, inclusive • endIndex (integer): the end index, inclusive • Return value • (String): substring of str • Example: • substring("Galaxy", 2, 5) = "lax" toUpperCase( str ) Returns an uppercased version of a string. • Parameters: • str (String): input string • Return value • (String): uppercased version of str • Example: • toUpperCase("Universe") = "UNIVERSE" toLowerCase( str ) Returns an lowercased version of a string. • Parameters: • str (String): input string • Return value • (String): lowercased version of str • Example: • toLowerCase("Universe") = "universe" trim( str ) Trims whitespace from both ends of a string. • Parameters: • str (String): input string • Return value • (String): str with any spaces trimmed from start and finish • Examples: • trim(" some text ") = "some text" • trim("some text") = "some text" padWithZeros( value, ndigit ) Takes an integer argument and returns a string representing the same numeric value but padded with leading zeros to a specified length. • Parameters: • value (long integer): numeric value to pad • ndigit (integer): the number of digits in the resulting string • Return value • (String): a string evaluating to the same as value with at least ndigit characters • Example: • padWithZeros(23,5) = "00023" desigToRa( designation ) Attempts to determine the ICRS Right Ascension from an IAU-style designation such as "2MASS J04355524+1630331" following the specifications in the document https://cdsweb.u-strasbg.fr/Dic/iau-spec.html. Note: this function should be used with considerable care. Such designators are intended for object identification and not for communicating sky positions, so that the resulting positions are likely to lack precision, and may be inaccurate. If positional information is available from other sources, it should almost certainly be used instead. But if there's no other choice, this may be used as a fallback. Note also that a designator with no coordsystem-specific flag character (a leading "J", "B" or "G") is considered to be B1950, not J2000. • Parameters: • designation (String): designation string in IAU format • Return value • (floating point): ICRS right ascension in degreees, or blank if no position can be decoded • Examples: • desigToRa("2MASS J04355524+1630331") = 60.98016 • desigToRa("PSR J120000.0+450000.0") = 180 • desigToDec("PSR B120000.0+450000.0") = 180.639096 • desigToRa("PN G001.2-00.3") = 267.403 • desigToRa("NGC 4993") = NaN desigToDec( designation ) Attempts to determine the ICRS Declination from an IAU-style designation such as "2MASS J04355524+1630331" following the specifications in the document https://cdsweb.u-strasbg.fr/Dic/iau-spec.html. Note: this function should be used with considerable care. Such designators are intended for object identification and not for communicating sky positions, so that the resulting positions are likely to lack precision, and may be inaccurate. If positional information is available from other sources, it should almost certainly be used instead. But if there's no other choice, this may be used as a fallback. Note also that a designator with no coordsystem-specific flag character (a leading "J", "B" or "G") is considered to be B1950, not J2000. • Parameters: • designation (String): designation string in IAU format • Return value • (floating point): ICRS declination in degrees, or blank if no position can be decoded • Examples: • desigToDec("2MASS J04355524+1630331") = 16.50919 • desigToDec("PSR J120000.0+450000.0") = 45 • desigToDec("PSR B120000.0+450000.0") = 44.72167 • desigToDec("PN G001.2-00.3") = -28.06457 • desigToDec("NGC 4993") = NaN desigToIcrs( designation ) Attempts to decode an IAU-style designation such as "2MASS J04355524+1630331" to determine its sky position, following the specifications in the document https://cdsweb.u-strasbg.fr/Dic/iau-spec.html. Obviously, this only works where the sequence part of the designation takes one of the family of coordinate-based forms. Note: this function should be used with considerable care. Such designators are intended for object identification and not for communicating sky positions, so that the resulting positions are likely to lack precision, and may be inaccurate. If positional information is available from other sources, it should almost certainly be used instead. But if there's no other choice, this may be used as a fallback. Note also that a designator with no coordsystem-specific flag character (a leading "J", "B" or "G") is considered to be B1950, not J2000. • Parameters: • designation (String): designation string in IAU format • Return value • (array of floating point): 2-element array giving ICRS (RA,Dec) in degrees, or null if no position can be decoded #### 10.6.17 Tilings Pixel tiling functions for the celestial sphere. The k parameter for the HEALPix functions is the HEALPix order, which can be in the range 0<=k<=29. This is the logarithm to base 2 of the HEALPix NSIDE parameter. At order k, there are 12*4^k pixels on the sphere. htmIndex( level, lon, lat ) Gives the HTM (Hierachical Triangular Mesh) pixel index for a given sky position. • Parameters: • level (integer): HTM level • lon (floating point): longitude in degrees • lat (floating point): latitude in degrees • Return value • (long integer): pixel index • See Also: healpixNestIndex( k, lon, lat ) Gives the pixel index for a given sky position in the HEALPix NEST scheme. • Parameters: • k (integer): HEALPix order (0..29) • lon (floating point): longitude in degrees • lat (floating point): latitude in degrees • Return value • (long integer): pixel index • See Also: healpixRingIndex( k, lon, lat ) Gives the pixel index for a given sky position in the HEALPix RING scheme. • Parameters: • k (integer): HEALPix order (0..29) • lon (floating point): longitude in degrees • lat (floating point): latitude in degrees • Return value • (long integer): pixel index • See Also: healpixNestLon( k, index ) Returns the longitude of the approximate center of the tile with a given index in the HEALPix NEST scheme. Note: the index parameter is 0-based, unlike the table row index special token $index (a.k.a. $0), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value $index-1 should be used.

• Parameters:
• k (integer): HEALPix order (0..29)
• index (long integer): healpix index
• Return value
• (floating point): longitude in degrees

healpixNestLat( k, index )
Returns the latitude of the approximate center of the tile with a given index in the HEALPix NEST scheme.

Note: the index parameter is 0-based, unlike the table row index special token $index (a.k.a. $0), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value $index-1 should be used. • Parameters: • k (integer): HEALPix order (0..29) • index (long integer): healpix index • Return value • (floating point): latitude in degrees • See Also: healpixRingLon( k, index ) Returns the longitude of the approximate center of the tile with a given index in the HEALPix RING scheme. Note: the index parameter is 0-based, unlike the table row index special token $index (a.k.a. $0), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value $index-1 should be used.

• Parameters:
• k (integer): HEALPix order (0..29)
• index (long integer): healpix index
• Return value
• (floating point): longitude in degrees

healpixRingLat( k, index )
Returns the latitude of the approximate center of the tile with a given index in the HEALPix RING scheme.

Note: the index parameter is 0-based, unlike the table row index special token $index (a.k.a. $0), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value $index-1 should be used. • Parameters: • k (integer): HEALPix order (0..29) • index (long integer): healpix index • Return value • (floating point): latitude in degrees • See Also: healpixNestToRing( k, nestIndex ) Converts a healpix tile index from the NEST to the RING scheme at a given order. Note: the nestIndex parameter is 0-based, unlike the table row index special token $index (a.k.a. $0), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value $index-1 should be used.

• Parameters:
• k (integer): HEALPix order (0..29)
• nestIndex (long integer): pixel index in NEST scheme
• Return value
• (long integer): pixel index in RING scheme

healpixRingToNest( k, ringIndex )
Converts a healpix tile index from the RING to the NEST scheme at a given order.

Note: the ringIndex parameter is 0-based, unlike the table row index special token $index (a.k.a. $0), which is 1-based. So if the HEALpix index is implicitly determined by the table row, the value $index-1 should be used. • Parameters: • k (integer): HEALPix order (0..29) • ringIndex (long integer): pixel index in RING scheme • Return value • (long integer): pixel index in NEST scheme • See Also: healpixK( pixelsize ) Gives the HEALPix resolution parameter suitable for a given pixel size. This k value (also variously known as order, level, depth) is the logarithm to base 2 of the Nside parameter. • Parameters: • pixelsize (floating point): pixel size in degrees • Return value • (integer): HEALPix order k • See Also: healpixResolution( k ) Gives the approximate resolution in degrees for a given HEALPix resolution parameter k This k value is the logarithm to base 2 of the Nside parameter. • Parameters: • k (integer): HEALPix order (0..29) • Return value • (floating point): approximate angular resolution in degrees healpixSteradians( k ) Returns the solid angle in steradians of each HEALPix pixel at a given order. • Parameters: • k (integer): HEALPix order (0..29) • Return value • (floating point): pixel size in steradians • Examples: • healpixSteradians(5) = 0.0010226538585904274 • 4*PI/healpixSteradians(0) = 12.0 healpixSqdeg( k ) Returns the solid angle in square degrees of each HEALPix pixel at a given order. • Parameters: • k (integer): HEALPix order (0..29) • Return value • (floating point): pixel size in steradians • Examples: • healpixSqdeg(5) = 3.357174580844667 • round(12 * healpixSqdeg(0)) = 41253 steradiansToSqdeg( sr ) Converts a solid angle from steradians to square degrees. The unit sphere is 4*PI steradians = 360*360/PI square degrees. • Parameters: • sr (floating point): quantity in steradians • Return value • (floating point): quantity in sqare degrees • Example: • round(steradiansToSqdeg(4*PI)) = 41253 sqdegToSteradians( sqdeg ) Converts a solid angle from square degrees to steradians. The unit sphere is 4*PI steradians = 360*360/PI square degrees. • Parameters: • sqdeg (floating point): quantity in square degrees • Return value • (floating point): quantity in steradians • Example: • round(sqdegToSteradians(41253)/PI) = 4 htmLevel( pixelsize ) Gives the HTM level parameter suitable for a given pixel size. • Parameters: • pixelsize (floating point): required resolution in degrees • Return value • (integer): HTM level parameter htmResolution( level ) Gives the approximate resolution in degrees for a given HTM depth level. • Parameters: • level (integer): HTM depth • Return value • (floating point): approximate angular resolution in degrees SQDEG Solid angle in steradians corresponding to 1 square degree. #### 10.6.18 Times Functions for conversion of time values between various forms. The forms used are Modified Julian Date (MJD) A continuous measure in days since midnight at the start of 17 November 1858. Based on UTC. ISO 8601 A string representation of the form yyyy-mm-ddThh:mm:ss.s, where the T is a literal character (a space character may be used instead). Based on UTC. Julian Epoch A continuous measure based on a Julian year of exactly 365.25 days. For approximate purposes this resembles the fractional number of years AD represented by the date. Sometimes (but not here) represented by prefixing a 'J'; J2000.0 is defined as 2000 January 1.5 in the TT timescale. Besselian Epoch A continuous measure based on a tropical year of about 365.2422 days. For approximate purposes this resembles the fractional number of years AD represented by the date. Sometimes (but not here) represented by prefixing a 'B'. Decimal Year Fractional number of years AD represented by the date. 2000.0, or equivalently 1999.99recurring, is midnight at the start of the first of January 2000. Because of leap years, the size of a unit depends on what year it is in. Therefore midday on the 25th of October 2004 is 2004-10-25T12:00:00 in ISO 8601 format, 53303.5 as an MJD value, 2004.81588 as a Julian Epoch and 2004.81726 as a Besselian Epoch. Currently this implementation cannot be relied upon to better than a millisecond. isoToMjd( isoDate ) Converts an ISO8601 date string to Modified Julian Date. The basic format of the isoDate argument is yyyy-mm-ddThh:mm:ss.s, though some deviations from this form are permitted: • The 'T' which separates date from time can be replaced by a space • The seconds, minutes and/or hours can be omitted • The decimal part of the seconds can be any length, and is optional • A 'Z' (which indicates UTC) may be appended to the time Some legal examples are therefore: "1994-12-21T14:18:23.2", "1968-01-14", and "2112-05-25 16:45Z". • Parameters: • isoDate (String): date in ISO 8601 format • Return value • (floating point): modified Julian date corresponding to isoDate • Examples: • isoToMjd("2004-10-25T18:00:00") = 53303.75 • isoToMjd("1970-01-01") = 40587.0 dateToMjd( year, month, day, hour, min, sec ) Converts a calendar date and time to Modified Julian Date. • Parameters: • year (integer): year AD • month (integer): index of month; January is 1, December is 12 • day (integer): day of month (the first day is 1) • hour (integer): hour (0-23) • min (integer): minute (0-59) • sec (floating point): second (0<=sec<60) • Return value • (floating point): modified Julian date corresponding to arguments • Example: • dateToMjd(1999, 12, 31, 23, 59, 59.) = 51543.99998 dateToMjd( year, month, day ) Converts a calendar date to Modified Julian Date. • Parameters: • year (integer): year AD • month (integer): index of month; January is 1, December is 12 • day (integer): day of month (the first day is 1) • Return value • (floating point): modified Julian date corresponding to 00:00:00 of the date specified by the arguments • Example: • dateToMjd(1999, 12, 31) = 51543.0 decYearToMjd( decYear ) Converts a Decimal Year to a Modified Julian Date. • Parameters: • decYear (floating point): decimal year • Return value • (floating point): modified Julian Date • Example: • decYearToMjd(2000.0) = 51544.0 isoToUnixSec( isoDate ) Converts an ISO8601 date string to seconds since 1970-01-01. The basic format of the isoDate argument is yyyy-mm-ddThh:mm:ss.s, though some deviations from this form are permitted: • The 'T' which separates date from time can be replaced by a space • The seconds, minutes and/or hours can be omitted • The decimal part of the seconds can be any length, and is optional • A 'Z' (which indicates UTC) may be appended to the time Some legal examples are therefore: "1994-12-21T14:18:23.2", "1968-01-14", and "2112-05-25 16:45Z". • Parameters: • isoDate (String): date in ISO 8601 format • Return value • (floating point): seconds since the Unix epoch • Examples: • isoToUnixSec("2004-10-25T18:00:00") = 1098727200 • isoToMjd("1970-01-01") = 0 decYearToUnixSec( decYear ) Converts a Decimal Year to seconds since 1970-01-01. • Parameters: • decYear (floating point): decimal year • Return value • (floating point): seconds since the Unix epoch • Examples: • decYearToUnixSec(2000.0) = 946684800 • decYearToUnixSec(1970) = 0 mjdToUnixSec( mjd ) Converts a Modified Julian Date to seconds since 1970-01-01. • Parameters: • mjd (floating point): modified Julian date • Return value • (floating point): seconds since the Unix epoch julianToUnixSec( jd ) Converts a Julian day to seconds since 1970-01-01. • Parameters: • jd (floating point): Julian day • Return value • (floating point): seconds since the Unix epoch mjdToIso( mjd ) Converts a Modified Julian Date value to an ISO 8601-format date-time string. The output format is yyyy-mm-ddThh:mm:ss. • Parameters: • mjd (floating point): modified Julian date • Return value • (String): ISO 8601 format date corresponding to mjd • Example: • mjdToIso(53551.72917) = "2005-06-30T17:30:00" mjdToDate( mjd ) Converts a Modified Julian Date value to an ISO 8601-format date string. The output format is yyyy-mm-dd. • Parameters: • mjd (floating point): modified Julian date • Return value • (String): ISO 8601 format date corresponding to mjd • Example: • mjdToDate(53551.72917) = "2005-06-30" mjdToTime( mjd ) Converts a Modified Julian Date value to an ISO 8601-format time-only string. The output format is hh:mm:ss. • Parameters: • mjd (floating point): modified Julian date • Return value • (String): ISO 8601 format time corresponding to mjd • Example: • mjdToTime(53551.72917) = "17:30:00" mjdToDecYear( mjd ) Converts a Modified Julian Date to Decimal Year. • Parameters: • mjd (floating point): modified Julian Date • Return value • (floating point): decimal year • Example: • mjdToDecYear(0.0) = 1858.87671 formatMjd( mjd, format ) Converts a Modified Julian Date value to a date using a customisable date format. The format is as defined by the java.text.SimpleDateFormat class. The default output corresponds to the string "yyyy-MM-dd'T'HH:mm:ss" Note that the output from certain formatting characters (such as MMM for month, EEE for day of week) is dependent on your locale (system language settings). The output time zone however always corresponds to UTC. • Parameters: • mjd (floating point): modified Julian date • format (String): formatting patttern • Return value • (String): custom formatted time corresponding to mjd • Examples: • formatMjd(50000.3, "EEE dd, MMM, yy") = "Tue 10 Oct, 95" • formatMjd(50000.1234, "'time 'H:mm:ss.SSS") = "time 2:57:41.760" mjdToJulian( mjd ) Converts a Modified Julian Date to Julian Epoch. For approximate purposes, the result of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 2000.5 is approximately 1 July 2000. • Parameters: • mjd (floating point): modified Julian date • Return value • (floating point): Julian epoch • Example: • mjdToJulian(0.0) = 1858.87885 julianToMjd( julianEpoch ) Converts a Julian Epoch to Modified Julian Date. For approximate purposes, the argument of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 2000.5 is approximately 1 July 2000. • Parameters: • julianEpoch (floating point): Julian epoch • Return value • (floating point): modified Julian date • Example: • julianToMjd(2000.0) = 51544.5 mjdToBesselian( mjd ) Converts Modified Julian Date to Besselian Epoch. For approximate purposes, the result of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 1950.5 is approximately 1 July 1950. • Parameters: • mjd (floating point): modified Julian date • Return value • (floating point): Besselian epoch • Example: • mjdToBesselian(0.0) = 1858.87711 besselianToMjd( besselianEpoch ) Converts Besselian Epoch to Modified Julian Date. For approximate purposes, the argument of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 1950.5 is approximately 1 July 1950. • Parameters: • besselianEpoch (floating point): Besselian epoch • Return value • (floating point): modified Julian date • Example: • besselianToMjd(1950.0) = 33281.92346 unixMillisToMjd( unixMillis ) Converts from milliseconds since the Unix epoch (1970-01-01T00:00:00) to a modified Julian date value • Parameters: • unixMillis (long integer): milliseconds since the Unix epoch • Return value • (floating point): modified Julian date mjdToUnixMillis( mjd ) Converts from modified Julian date to milliseconds since the Unix epoch (1970-01-01T00:00:00). • Parameters: • mjd (floating point): modified Julian date • Return value • (long integer): milliseconds since the Unix epoch #### 10.6.19 TrigDegrees Standard trigonometric functions with angles in degrees. sinDeg( theta ) Sine of an angle. • Parameters: • theta (floating point): an angle, in degrees • Return value • (floating point): the sine of the argument cosDeg( theta ) Cosine of an angle. • Parameters: • theta (floating point): an angle, in degrees • Return value • (floating point): the cosine of the argument tanDeg( theta ) Tangent of an angle. • Parameters: • theta (floating point): an angle, in degrees • Return value • (floating point): the tangent of the argument. asinDeg( x ) Arc sine. The result is in the range of -90 through 90. • Parameters: • x (floating point): the value whose arc sine is to be returned. • Return value • (floating point): the arc sine of the argument in degrees acosDeg( x ) Arc cosine. The result is in the range of 0.0 through 180. • Parameters: • x (floating point): the value whose arc cosine is to be returned. • Return value • (floating point): the arc cosine of the argument in degrees atanDeg( x ) Arc tangent. The result is in the range of -90 through 90. • Parameters: • x (floating point): the value whose arc tangent is to be returned. • Return value • (floating point): the arc tangent of the argument in degrees atan2Deg( y, x ) Converts rectangular coordinates (x,y) to polar (r,theta). This method computes the phase theta by computing an arc tangent of y/x in the range of -180 to 180. • Parameters: • y (floating point): the ordinate coordinate • x (floating point): the abscissa coordinate • Return value • (floating point): the theta component in degrees of the point (r,theta) in polar coordinates that corresponds to the point (x,y) in Cartesian coordinates. #### 10.6.20 URLs Functions that construct URLs for external services. Most of the functions here just do string manipulation to build up URL strings, using knowledge of the parameters required for various services. urlEncode( txt ) Performs necessary quoting of a string for it to be included safely in the data part of a URL. Alphanumeric characters and the characters underscore ("_"), minus sign ("-"), period (".") and tilde ("~") are passed through unchanged, and any other 7-bit ASCII character is represented by a percent sign ("%") followed by its 2-digit hexadecimal code. Characters with values of 128 or greater are simply dropped. • Parameters: • txt (String): input (unencoded) string • Return value • (String): output (encoded) string • Example: • urlEncode("RR Lyr") = "RR%20Lyr" • See Also: urlDecode( txt ) Reverses the quoting performed by urlEncode. Percent-encoded sequences (%xx) are replaced by the ASCII character with the hexadecimal code xx. • Parameters: • txt (String): input (encoded) string • Return value • (String): output (unencoded) string • Example: • urlDecode("RR%20Lyr") = "RR Lyr" • See Also: paramsUrl( baseUrl, nameValuePairs, ... ) Builds a query-type URL string given a base URL and a list of name, value pairs. The parameters are encoded on the command line according to the "application/x-www-form-urlencoded" convention, which appends a "?" to the base URL, and then adds name=value pairs separated by "&" characters, with percent-encoding of non-URL-friendly characters. This format is used by many services that require a list of parameters to be conveyed on the URL. • Parameters: • baseUrl (String): basic URL (may or may not already contain a "?") • nameValuePairs (String, one or more): an even number of arguments (or an even-length string array) giving parameter name1,value1,name2,value2,...nameN,valueN • Return value • (String): form-encoded URL • Example: • paramsUrl("http://x.org/", "a", "1", "b", "two", "c", "3&4") = "http://x.org/?a=1&b=two&c=3%264" bibcodeUrl( bibcode ) Maps a bibcode to the URL that will display the relevant entry in ADS. If the supplied string does not appear to be a bibcode, null will be returned. If the supplied string appears to be a bibcode, it just prepends the string "https://ui.adsabs.harvard.edu/abs/" and performs any character escaping that is required. • Parameters: • bibcode (String): ADS-style bibcode string • Return value • (String): display URL pointing at bibcode record, or null if it doesn't look like a bibcode • Example: • bibcodeUrl("2018A&A...616A...2L") = "https://ui.adsabs.harvard.edu/abs/2018A%26A...616A...2L" • See Also: doiUrl( doi ) Maps a DOI (Digital Object Identifier) to its dislay URL. If the supplied string does not appear to be a DOI, null will be returned. If the supplied string appears to be a DOI, it strips any "doi:" prefix if present, prepends the string "https://doi.org/", and performs any character escaping that is required. • Parameters: • doi (String): DOI string, with or without "doi:" prefix • Return value • (String): display URL pointing at DOI content, or null if it doesn't look like a DOI • Example: • doiUrl("10.3390/informatics4030018") = "https://doi.org/10.3390/informatics4030018" • See Also: arxivUrl( arxivId ) Maps an arXiv identifier to the URL that will display its arXiv web page. If the supplied string does not appear to be an arXiv identifier, null will be returned. If the supplied string appears to be an arXiv identifier, it strips any "arXiv: prefix and prepends the string "https://arxiv.org/abs/". • Parameters: • arxivId (String): arXiv identifier, with or without "arXiv:" prefix • Return value • (String): display URL pointing at bibcode record, or null if it doesn't look like a bibcode • Example: • arxivUrl("arXiv:1804.09379") = "https://arxiv.org/abs/1804.09381" • See Also: simbadUrl( sourceId ) Maps a source identifier to the URL of its SIMBAD web page. SIMBAD is the astronomical source information service run by the Centre de Données astronomiques de Strasbourg. The string "http://simbad.u-strasbg.fr/simbad/sim-id?Ident=" is prepended to the given id string, and any necessary character escaping is applied. No attempt is made to validate whether the supplied string is a real source identifier, so there is no guarantee that the returned URL will contain actual results. • Parameters: • sourceId (String): free text assumed to represent a source identifier known by SIMBAD • Return value • (String): URL of the Simbad web page describing the identified source • Example: • simbadUrl("Beta Pictoris") = "http://simbad.u-strasbg.fr/simbad/sim-id?Ident=Beta%20Pictoris" nedUrl( sourceId ) Maps a source identifier to the URL of its NED web page. NED is the NASA/IPAC Extragalactic Database. The string "http://ned.ipac.caltech.edu/byname?objname=" is prepended to the given id string, and any necessary character escaping is applied. No attempt is made to validate whether the supplied string is a real source identifier, so there is no guarantee that the returned URL will contain actual results. • Parameters: • sourceId (String): free text assumed to represent a source identifier known by NED • Return value • (String): URL of the NED web page describing the identified source • Example: • nedUrl("NGC 3952") = "http://ned.ipac.caltech.edu/byname?objname=NGC%203952" hips2fitsUrl( hipsId, fmt, raDeg, decDeg, fovDeg, npix ) Returns the URL of a cutout from the Hips2Fits service operated by CDS. The result will be the URL of a FITS or image file resampled to order from one of the HiPS surveys available at CDS. This function requests a square cutout using the SIN projection, which is suitable for small cutouts. If the details of this function don't suit your purposes, you can construct the URL yourself. • Parameters: • hipsId (String): identifier or partial identifier for the HiPS survey • fmt (String): required output format, for instance "fits", "png", "jpg" • raDeg (floating point): central Right Ascension (longitude) in degrees • decDeg (floating point): central Declination (latitude) in degrees • fovDeg (floating point): field of view; extent of the cutout in degrees • npix (integer): extent of the cutout in pixels (width=height=npix) • Return value • (String): URL of the required cutout • See Also: ### 10.7 Examples Here are some examples for defining new columns; the expressions below could appear as the <expr> in a tpipe addcol or sortexpr command). Average  (first + second) * 0.5  Square root  sqrt(variance)  Angle conversion  radiansToDegrees(DEC_radians) degreesToRadians(RA_degrees)  Conversion from string to number  parseInt($12)
parseDouble(ident)

Conversion from number to string
   toString(index)

Conversion between numeric types
   toShort(obs_type)
toDouble(range)

or
   (short) obs_type
(double) range

Conversion from sexagesimal to degrees
   hmsToDegrees(RA1950)
dmsToDegrees(decDeg,decMin,decSec)

Conversion from degrees to sexagesimal
   degreesToDms($3) degreesToHms(RA,2)  Outlier clipping  min(1000, max(value, 0))  Converting a magic value to null  jmag == 9999 ? NULL : jmag  Converting a null value to a magic one  NULL_jmag ? 9999 : jmag  Taking the third scalar element from an array-valued column  psfCounts[2]  Converting spectral type to numeric value (e.g. "L3.5" -> 23.5, "M7" -> 17)  "MLT".indexOf(spType.charAt(0)) * 10 + parseDouble(substring(spType,1)) + 10  Note this uses a couple of Java String instance methods (Section 10.8.2) which are not explicitly documented in this section. Here are some examples of boolean expressions that could be used for row selection (appearing in a tpipe select command) Within a numeric range  RA > 100 && RA < 120 && Dec > 75 && Dec < 85  Within a circle $2*$2 +$3*$3 < 1 skyDistanceDegrees(ra0,dec0,hmsToDegrees(RA),dmsToDegrees(DEC))<15./3600.  First 100 rows  index <= 100  (though you could use tpipe cmd='head 100' instead) Every tenth row  index % 10 == 0  (though you could use tpipe cmd='every 10' instead) String equality/matching  equals(SECTOR, "ZZ9 Plural Z Alpha") equalsIgnoreCase(SECTOR, "zz9 plural z alpha") startsWith(SECTOR, "ZZ") contains(ph_qual, "U")  String regular expression matching  matches(SECTOR, "[XYZ] Alpha")  Test for non-blank value  ! NULL_ellipticity  ### 10.8 Advanced Topics This section contains some notes on getting the most out of the algebraic expressions facility. If you're not a Java programmer, some of the following may be a bit daunting - read on at your own risk! #### 10.8.1 Expression evaluation This note provides a bit more detail for Java programmers on what is going on here; it describes how the use of functions in STILTS algebraic expressions relates to normal Java code. The expressions which you write are compiled to Java bytecode when you enter them (if there is a 'compilation error' it will be reported straight away). The functions listed in the previous subsections are all the public static methods of the classes which are made available by default. The classes listed are all in the package uk.ac.starlink.ttools.func. However, the public static methods are all imported into an anonymous namespace for bytecode compilation, so that you write (sqrt(x,y) and not Maths.sqrt(x,y). The same happens to other classes that are imported (which can be in any package or none) - their public static methods all go into the anonymous namespace. Thus, method name clashes are a possibility. This cleverness is all made possible by the rather wonderful JEL. #### 10.8.2 Instance Methods There is another category of functions which can be used apart from those listed in Section 10.6. These are called, in Java/object-oriented parlance, "instance methods" and represent functions that can be executed on an object. It is possible to invoke any of its public instance methods on any object (though not on primitive values - numeric and boolean ones). The syntax is that you place a "." followed by the method invocation after the object you want to invoke the method on, hence NAME.substring(3) instead of substring(NAME,3). If you know what you're doing, feel free to go ahead and do this. However, most of the instance methods you're likely to want to use have equivalents in the normal functions listed in the previous section, so unless you're a Java programmer or feeling adventurous, you may be best off ignoring this feature. #### 10.8.3 Adding User-Defined Functions The functions provided by default for use with algebraic expressions, while powerful, may not provide all the operations you need. For this reason, it is possible to write your own extensions to the expression language. In this way you can specify abritrarily complicated functions. Note however that this will only allow you to define new columns or subsets where each cell is a function only of the other cells in the same row - it will not allow values in one row to be functions of values in another. In order to do this, you have to write and compile a (probably short) program in the Java language. A full discussion of how to go about this is beyond the scope of this document, so if you are new to Java and/or programming you may need to find a friendly local programmer to assist (or mail the author). The following explanation is aimed at Java programmers, but may not be incomprehensible to non-specialists. The steps you need to follow are: 1. Write and compile a class containing one or more static public methods representing the function(s) required 2. Make this class available on the application's classpath at runtime as described in Section 3.1 3. Specify the class's name to the application, as the value of the jel.classes system property (colon-separated if there are several) as described in Section 3.3 Any public static methods defined in the classes thus specified will then be available for use. They should be defined to take and return the relevant primitive or Object types for the function required. For instance a class written as follows would define a three-value average:  public class AuxFuncs { public static double average3(double x, double y, double z) { return (x + y + z) / 3.0; } }  and the command  stilts tpipe cmd='addcol AVERAGE "average3($1,$2,$3)"'

would add a new column named AVERAGE giving the average of the first three existing columns. Exactly how you would build this is dependent on your system, but it might involve doing something like the following:
1. Writing a file named AuxFuncs.java containing the above code
2. Compiling it using a command like "javac AuxFuncs.java"
3. Running tpipe using the flags "stilts -classpath . -Djel.classes=AuxFuncs tpipe"

Note that (in versions later than STILTS 3.0-6) variable-length argument lists are supported where the final declared argument is an array, so for instance a method declared like:

       public static double sum(double[] values) {
double total = 0;
for (int i = 0; i < values.length; i++) {
total += values[i];
}
}

can be invoked like "sum(UMAG,GMAG,RMAG,IMAG,ZMAG)". The alternative form "double... values" can be used in the declaration with identical effect.

## 11 Server Mode

STILTS is generally run by issuing commands from some kind of command line. However, facilities are also included to run it as a service, accepting commands via HTTP. The basic implementation of this is in the form of some Servlet implementations that can be run in a servlet container. At present the following servlets are provided:

In order to run them there are a few options:

STILTS server command
The simplest is to use the STILTS server command. If you run this, the services will start up immediately and print information about the base URL. Some configuration of available functions and data access is offered by the command line parameters. This command is a thin wrapper around the Jetty servlet engine which is included in the STILTS distribution.
Deploy in a servlet container
For more control you can deploy the servlet or servlets you want to run in a servlet container of your choice, for instance Tomcat. The servlets can be configured by setting context parameters in a web.xml file in the usual way; look at the StiltsContext class to see the available configuration parameters.
Docker
In the case of the plot server, a Docker container has been provided for convenience. At time of writing this is available, with some more discussion about how to deploy it, at https://hub.docker.com/r/mbtaylor/plotserv.
In all cases, look at the base URL of the running service for more information and usage examples. For instance if the server is running at the default base URL, then pointing your browser at
    http://localhost:2112/stilts/

will show you links to documentation for the available services.

The different services are described further in the following subsections.

Note: The server command and associated servlet code are somewhat experimental. If you have requirements which are not currently provided, please contact the author for discussion.

### 11.1 Plot Service

The plot server supports interactive plots that can be viewed and navigated using HTTP requests. A plot is specified with a URL, corresponding to an invocation of one of the plot2* commands, that specifies a plot, and uses a service API that can be used by client-side javascript to display and update a plot image in response to user navigation actions such as mouse drag and wheel gestures. The effect is of an interactive plot in a web browser that can be navigated with the mouse in exactly the same way as a STILTS or TOPCAT interactive plot.

To see this in action, run

   % stilts server


The following subsections give some more details about how this works and how it can be used.

#### 11.1.1 Usage

The best way to see how the plot service can be used is to run the service (most simply by executing stilts server), and look at the running plot examples, along with their HTML source code, served from the server endpoint.

However this section gives a brief independent overview of how the service can be used. The PlotServlet itself exposes a RESTful API as described in Section 11.1.2. This offers the services required for client HTML/JavaScript code running in a browser to set up a plot based on server-side (or at least server-accessible) table data, and to make updates to it following user activity like mouse gestures.

A basic client JavaScript library named plot2Lib.js, that facilitates this plot setup is included with STILTS; it can be found in the stilts.jar file at uk/ac/starlink/ttools/server/plot2Lib.js, and is available from the running server at <plot-service-base>/plot2Lib.js. It exports some variables in the plot2 namespace; see comments in the file itself for documentation of how to use it. A minimal web page using this to present an interactive plot might look like:

   <html>
<script src="plot2Lib.js"></script>
<script>
var serverUrl = "http://localhost:2112/stilts/plot/";
var plotTxt = plot2.wordsToPlotTxt([
"plot2sky",
"layer1=mark",
"in1=/data/catalogue.fits",
"lon1=RA",
"lat1=DEC"
]);
var plotNode = plot2.createPlotNode(serverUrl, plotTxt);
document.getElementsByTagName("body")[0].appendChild(plotNode);
};
</script>
</html>

In this case the data file "/data/catalogue.fits" has to be available to the servlet; how this is arranged depends on the way the service is deployed.

JavaScript clients don't have to use the plot2Lib.js library; it's also possible to write custom code that talks to the RESTful API described in Section 11.1.2.

#### 11.1.2 RESTful API

This section details the endpoints supported by the plot servlet; it is not required reading for those who want to use the supplied plot2Lib.js JavaScript library, but may be of interest to those who want to write their own JavaScript clients.

General URL Syntax

The plot service accepts URLs of the form

   <base-url>/<action-type>/<plot-spec>[?<session-id>&<arg-list>]


These parts are expanded as follows:

<action-type>
The action type string determines the kind of request, and is one of the strings "html", "state", "imgsrc", "position", "count", "row"; see below for details.
<plot-spec>
The plot specification is an ampersand-separated STILTS plot command string; the form is "<command-name>&<arg-name>=<value>&<arg-name>=<value>..." for instance "plot2sky&layer1=mark&in1=stars.vot&lon1=ra&lat1=dec". See STILTS plotting documentation in Section 8 for command syntax. Note that although this part contains &-separated name=value pairs which are syntactically application/x-www-form-urlencoded it is part of the URI path and not a URI query string since it does not come after a question mark ('?') and it cannot be supplied by POSTing parameters.
<session-id>
The session identifier is of the form "sessionId=<unique-string>" and it serves to maintain the state of the plot between requests (so that for instance a navigation action starts from where the last one left off). The <unique-string> string is chosen by the client; any string value is permitted, but it's up to the client to pick something that is unlikely to be chosen by other unrelated clients on the same or different machines. Incorporating a high-resolution timestamp is a good bet. In case of a collision, confusing results may ensue, but it's probably not necessary to resort to cryptographic-grade hashing. This part is not necessary for the "html" <action-type>.
<arg-list>
A list of zero or more ampersand-separated "<name>=<value>" parameters, specific to the <action-type>; see below for details.

The [?<session-id>&<arg-list>] part of the URL is an application/x-www-form-urlencoded query-string, and may be supplied as a POST body rather than as part of the GET query if preferred. Note that does not apply to the <plot-spec> part, which is in RFC3986 terms part of the path and not part of the query.

Available Action Types

The options for the various different values of the <action-type> string, with their associated parameters and response values, are as follows:

html
Returns a new standalone HTML page containing the interactive plot specified by the supplied plot specification. Note this does not require a session ID to be supplied, and it has no parameters. This action is easy to use, but not very flexible.
state
Returns a JSON structure giving the image and/or image annotations for the current state of the session. The session state may be updated by supplying navigation parameters, as follows:
• navigate=reset: reset the plot to initial state
• navigate=resize&size=width,height: resize the plot to width x height pixels
• navigate=click&pos=x,y&ibutton=1|2|3: emulate TOPCAT click on plot at graphics position x,y
• navigate=drag&origin=x0,y0&pos=x1,y1&ibutton=1|2|3: emulate TOPCAT continuing drag from start graphics position x0,y0 to x1,y1
• navigate=drag&origin=x0,y0&pos=x1,y1&ibutton=1|2|3&end=true: emulate TOPCAT end-drag from start graphics position x0,y0 to x1,y1
• navigate=wheel&pos=x,y&wheelrot=nstep: emulate TOPCAT mouse wheel at graphics position x,y
• navigate=none: no change to last position

The members of the returned structure are:

imgSrc (present if plot has changed since last request):
Contains a data: URL suitable for use as the content of an IMG/@src attribute to display the current state of the plot
staticSvg (present if there are static decorations):
SVG content, suitable as the content of an SVG node, giving decorations to superimpose over the plot image.
transientSvg (present if there are transient decorations):
SVG content, suitable as the content of an SVG node, giving decorations to superimpose over the plot image representing a navigation action. Such decorations should only be displayed for a short time (e.g. 0.5 second).
bounds (present for planar and cubic plots):
A 2- or 3-element array of (lower,upper) data bound pairs giving the extent of the current plot.

imgsrc
Returns image data suitable for reference by an IMG/@src attribute value for the current state of the session. The session state may be updated by supplying navigation parameters as follows:
• navigate=reset: reset the plot to initial state
• navigate=resize&size=width,height: resize the plot to width x height pixels
• navigate=click&pos=x,y&ibutton=1|2|3: emulate TOPCAT click on plot at graphics position x,y
• navigate=drag&origin=x0,y0&pos=x1,y1&ibutton=1|2|3: emulate TOPCAT continuing drag from start graphics position x0,y0 to x1,y1
• navigate=drag&origin=x0,y0&pos=x1,y1&ibutton=1|2|3&end=true: emulate TOPCAT end-drag from start graphics position x0,y0 to x1,y1
• navigate=wheel&pos=x,y&wheelrot=nstep: emulate TOPCAT mouse wheel at graphics position x,y
• navigate=none: no change to last position

The response MIME type can be influenced by the ofmt parameter in the <plot-spec> or the format parameter in the <arg-list>. In case of disagreement, the latter takes precedence. The available options are "png", "png-transp", "gif", "jpeg", "pdf", "svg", "eps", "eps-gzip".

position
Provides a service to convert a position in plot graphics coordinates to data coordinates. The request must have a pos argument giving the graphics position in the form x,y (e.g. "pos=203,144"), and the response will be a JSON structure with the following members:
dataPos:
On success, contains data coordinates as a numeric array.
txtPos:
On success, contains data coordinates as a formatted string.
message:
Textual indication of conversion status. It will be "ok" on success, but may have some other value, such as "out of plot bounds", on failure.
count
Returns the number of points currently visible in this plot. Note that determining this value does take some computation (it's not free). The output is a plain text decimal value; it can also be interpreted as JSON.
row
Services a request for row information, at or near a submitted graphics position on the plot. The request must have a pos argument giving the graphics position in the form x,y (e.g. "pos=203,144"),

The output is a JSON array of objects; there is one array element for each table represented, and each such element is a column-name->column-value map for the row indicated. If the submitted point is not near any plotted points, the result will therefore be an empty array.

This API is subject to extension or modification in future releases.

#### 11.1.3 Caching and Performance

The plot servlet requires some temporary disk storage for caching images and prepared coordinate data to improve performance when updating plots during visualisation sequences. Servlet configuration options are available to manage usage of these resources.

When first requested to make a plot, it works out what coordinate data will be required, reads this from the input table, and writes it to cache in an efficient binary storage format. This may be simply a copy of columns from the input table, or may require some computation, for instance if the plotted quantity is the result of an expression in the expression language, or if the coordinates are longitude and latitude (in which case they are converted to unit vector components). This coordinate cache preparation requires a scan of the input table which is in the current implementation single-threaded, so may be time-consuming for very large tables.

Once the coordinate data is in cache, the cache rather than the input table is used for subsequent plots; that includes both derived replots resulting from user navigation and completely separate plots that happen to require the same row/column data. Plots from cache are in most cases multi-threaded, so can be quite rapid even for large datasets depending on server configuration and load.

When the plot is first made, the initial (pre-navigation) plotted image is also stored in a cache, so that if other HTTP clients request the same plot they can receive the initial image without further data access or computation.

By default, the directory used for caching is the value of the java.io.tmpdir system property, which is typically /tmp on Unix systems. The directory used for caching can be changed by modifying this system property, or caching can be configured with the servlet context parameters controlled by the StiltsContext class.

When cache storage gets full, older items are dropped in the usual way. There is no doubt scope for improvement of the existing cache management; the details may be refined in future releases.

This servlet allows execution of a single STILTS command by making an HTTP request with the command name and parameters, rather than by presenting them on the command line. You might want to run this service if you are providing a web service to external users which is able to access files residing on the server, for instance generating static table plots (though see the Plot service for more sophisticated server-side visualisation) or row selections on the fly. This can be done without the server mode, for instance by invoking the stilts script or java from a CGI script to serve each request, but using server mode has two advantages: first it provides correct output HTTP headers such as Content-Type, and secondly it avoids the Java startup overheads for each invocation.

The URLs accepted by the service are of the form

   <task-base-url>/<task-name>?<arg-name>=<arg-value>&<arg-name>=<arg-value>...

The <task-name> is one of the STILTS command names as listed in Appendix B, and the <arg-name>=<arg-value> pairs are the parameter settings for that command; the parameter settings are syntactically an application/x-www-form-urlencoded query string. These parameters may be supplied as a POST body rather than as part of a GET query if preferred, though since the task invocation will normally be idempotent, GET may be more respectable.

The HTTP response depends on the behaviour of the task in question. If the task is one that outputs a table or sequence of tables, such as tpipe or tmatch2, the HTTP response will be the serialized form of the table in an appropriate format. By default that is currently VOTable (Content-Type "application/x-votable+xml"), but that can be altered by supplying the appropriate output format parameter, e.g. "ofmt=fits". Plotting commands return an image in a default graphics format; again the output format can be controlled using command paramters in the same way as on the command line. Output for some other commands such as calc may just be plain text.

Here are some example invocations, assuming the default server base URL of http://localhost:2112/stilts/:

http://localhost:2112/stilts/

Returns an HTML page giving version information and some links to example usages of the server.
http://localhost:2112/stilts/task/tpipe

Returns an HTML page giving usage instructions for the tpipe task.
http://localhost:2112/stilts/task/calc?expression=21%2b2

Invokes the calc task to return a document containing the text "23". Note that the plus ("+") sign in the expression has to be encoded using the sequence "%2b" since "+" has a special significance in query URLs - see for instance sec 2.2 of RFC 1738.
http://localhost:2112/stilts/task/plot2plane?in=/data/table1.vot&layer1=mark&x1=RMAG&y1=BMAG

Invokes the plot2d task to return a magnitude-magnitude diagram of the named server-side file as an image, probably an image/png (but see the Plot Service if you want interactive plots).
http://localhost:2112/stilts/task/tcopy?in=/data/cat.fits&ofmt=ecsv

Invokes the tcopy task to return a translation of the named server-side FITS file to ECSV format.

Note that in the current form of this service no great attention has been paid to security, so it may be possible for clients to read and write files and expend significant system resources by making certain requests to the server. Anyone exposing this service directly to external clients should bear this in mind.

### 11.3 Form Service

The Form service is more or less obsolete; it really just gives an example of how to set up an HTML Form to invoke one of the STILTS commands using the Task Service.

The content served gives provides a couple of examples of an HTML form that can invoke plotting using the Task Service. The output graphics use the old-style plot commands rather than the much more capable plot2* plotting, and are not interactive; for much improved server-side visualisastion, see Section 11.1.

## 12 Programmatic Invocation

The STILTS package provides some capabilities, for instance plotting, that might be useful as part of other Java applications. The code that forms STILTS is fully documented at the API level; there are comprehensive javadocs throughout for the uk.ac.starlink.ttools package, its subpackages, and most of the other classes in the uk.ac.starlink tree on which it relies. Anybody is welcome to use these classes at their own risk, but the code does not form a stable API intended for public use: the javadocs are not distributed as part of the package (though you may be able to find them here), tutorial documentation is not provided, and there is no commitment to API stability between releases.

With this in mind, there are facilities for invoking the STILTS commands programmatically from third-party java code. Of course it is possible to do this by just calling the static main(String[]) method of the application Main-Class (Stilts) but we document here how it can be done in a way which allows more control, using the uk.ac.starlink.task parameter handling framework.

Each of the STILTS tasks listed in Appendix B is represented by a class implementing the Task interface; these all have no-arg constructors. To run it, you need to create an instance of the class, pass it an Environment object which can acquire values for parameters by name, and then execute it. The MapEnvironment class, based on a Map containing name/value pairs, is provided for this purpose. As well as managing parameter values, MapEnvironment captures table and text output in a way that lets you retrieve it after the task has executed. Here is a simple example for invoking the calc task to perform a simple calcation:

    MapEnvironment env = new MapEnvironment();
env.setValue( "expression", "sqrt(3*3+4*4)" );
String result = env.getOutputText();

The execution corresponds exactly to the command-line:
    stilts calc expression="sqrt(3*3+4*4)"

The Usage section for the calc task notes that the corresponding Task subclass is Calc.

Also in the usage section, each parameter reports the data type that it may take, and objects of this type may be used as the parameter value passed in the MapEnvironment as an alternative to passing string values. For the case of the input table parameters, this is StarTable, so in a task like tpipe (TablePipe), if you want to read a file "data.fits", you can either write

    env.setValue( "in", "data.fits" );

or
    StarTable table = new StarTableFactory().readStarTable( "data.fits" );
env.setValue( "in", table );

That doesn't buy you much, but the table could equally be obtained from any other source, including being a user-defined iterable over existing data structures. See SUN/252 for more information on StarTable handling.

For some short examples of programs which invoke STILTS tasks in this way, see the source code of some of the examples in the uk.ac.starlink.ttools.example directory: Calculator and Head10.

Some commands provide additional methods for use with parameter-based invocation. In particular the plotting commands can be used to create JComponent objects that can be incorporated into an existing GUI. A working example of this can be found in the source code for the example EnvPlanePlotter class. For some more tutorial introductions to using the plotting classes programmatically, see also the example classes SinePlot, ApiPlanePlotter, and BasicPlotGui in the same place.

## A Commands By Category

This section lists the commands available broken down by the category of function they provide. Some commands appear in more than one category. Detailed descriptions and examples for each command can be found in Appendix B.

Format conversion:
Generic table manipulation:
Crossmatching:
Plotting:
Sky Pixel Operations:
VOTables:
Virtual Observatory service access:
SQL Database access:
Miscellaneous:

## B Command Reference

This appendix provides the reference documentation for the commands in the package. For each one a description of its purpose, a list of its command-line arguments, and some examples are given.

## B.1 calc: Evaluates expressions

calc is a very simple utility for evaluating expressions. It uses the same expression evaluator as is used in tpipe and the other generic table tasks for things like creating new columns, so it can be used as a quick test to see what expressions work, or in order to evaluate expressions using the various algebraic functions documented in Section 10.6. Since usually no table is involved, you can't refer to column names in the expressions. It has one mandatory parameter, the expression to evaluate, and writes the result to the screen.

### B.1.1 Usage

The usage of calc is

   stilts <stilts-flags> calc table=<table>
[expression=]<expr>

If you don't have the stilts script installed, write "java -jar stilts.jar" instead of "stilts" - see Section 3. The available <stilts-flags> are listed in Section 2.1. For programmatic invocation, the Task class for this command is uk.ac.starlink.ttools.task.Calc.

Parameter values are assigned on the command line as explained in Section 2.3. They are as follows:

expression = <expr>       (String)
An expression to evaluate. The functions in Section 10.6 can be used.
table = <table>       (StarTable)
A table which provides the context within which expression is evaluated. This parameter is optional, and will usually not be required; its only purpose is to allow use of constant expressions (table parameters) associated with the table. These can be referenced using identifiers of the form param$*, ucd$* or utype$* - see Section 10.2 for more detail. ### B.1.2 Examples Here are some examples of using calc: stilts calc 1+2  Calculates one plus two. Writes "3" to standard output. stilts calc 'isoToMjd("2005-12-25T00:00:00")'  Works out the Modified Julian Day corresponding to Christmas 2005. The output is "53729.0". stilts calc 'param$author' table=catalogue.xml

In this case the expression is evaluated in the context of the supplied table, which means that the table's parameters can be referenced in the expression. This example just outputs the value of the table parameter named "author".

## B.2 cdsskymatch: Crossmatches table on sky position against VizieR/SIMBAD table

cdsskymatch uses the CDS X-Match service to join a local table to one of the tables hosted by the Centre de Données astronomiques de Strasbourg. This includes all of the VizieR tables and the SIMBAD database. The service is very fast, and in most cases it is the best way to match a local table against a large external table hosted by a service. It is almost certainly much better than using coneskymatch, though it is less flexible than TAP (see the tapquery task for flexible access to TAP services, and tapskymatch for positional matches).

The local table is uploaded to the X-Match service in chunks, and the matches for each chunk are retrieved in turn and eventually stitched together to form the final result. The tool only uploads sky position and an identifier for each row of the input table, but all columns of the input table are reinstated in the result for reference.

For a better understanding of the details of how this service operates, including exactly what coordinates are matched against the uploaded positions (roughly: integrated to J2000 using proper motions if available) and what columns are included in the output (roughly: a subset of the most commonly used columns), please consult the service documentation.

Acknowledgement: CDS note that if the use of the X-Match service is useful to your research, they would appreciate the following acknowledgement:

"This research made use of the cross-match service provided by CDS, Strasbourg."

### B.2.1 Usage

The usage of cdsskymatch is

   stilts <stilts-flags> cdsskymatch ifmt=<in-format> istream=true|false
icmd=<cmds> ocmd=<cmds>
out=<out-table> ofmt=<out-format>
ra=<expr> dec=<expr>
find=all|best|best-remote|each|each-dist
blocksize=<int-value> maxrec=<int-value>
compress=true|false
serviceurl=<url-value> usemoc=true|false
presort=true|false fixcols=none|dups|all
suffixin=<label> suffixremote=<label>
[in=]<table>

If you don't have the stilts script installed, write "java -jar stilts.jar" instead of "stilts" - see Section 3. The available <stilts-flags> are listed in Section 2.1. For programmatic invocation, the Task class for this command is uk.ac.starlink.ttools.task.CdsUploadSkyMatch.

Parameter values are assigned on the command line as explained in Section 2.3. They are as follows:

blocksize = <int-value>       (Integer)
The CDS Xmatch service operates limits on the maximum number of rows that can be uploaded and the maximum number of rows that is returned as a result from a single query. In the case of large input tables, they are broken down into smaller blocks, and one request is sent to the external service for each block. This parameter controls the number of rows in each block. For an input table with fewer rows than this value, the whole thing is done as a single request.

At time of writing, the maximum upload size is 100Mb (about 3Mrow; this does not depend on the width of your table), and the maximum return size is 2Mrow.

Large blocksizes tend to be good (up to a point) for reducing the total amount of time a large xmatch operation takes, but they can make it harder to see the job progressing. There is also the danger (for ALL-type find modes) of exceeding the return size limit, which will result in truncation of the returned result.

[Default: 50000]

cdstable = <value>       (String)
Identifier of the table from the CDS crossmatch service that is to be matched against the local table. This identifier may be the standard VizieR identifier (e.g. "II/246/out" for the 2MASS Point Source Catalogue) or "simbad" to indicate SIMBAD data.

See for instance the TAPVizieR table searching facility at http://tapvizier.u-strasbg.fr/adql/ to find VizieR catalogue identifiers.

compress = true|false       (Boolean)
If true, the service is requested to provide HTTP-level compression for the response stream (Accept-Encoding header is set to "gzip", see RFC 2616). This does not guarantee that compression will happen but if the service honours this request it may result in a smaller amount of network traffic at the expense of more processing on the server and client.

[Default: true]

dec = <expr>       (String)
Declination in degrees in the ICRS coordinate system for the position of each row of the input table. This may simply be a column name, or it may be an algebraic expression calculated from columns as explained in Section 10. If left blank, an attempt is made to guess from UCDs, column names and unit annotations what expression to use.
find = all|best|best-remote|each|each-dist       (UserFindMode)
Determines which pair matches are included in the result.
• all: All matches
• best: Matched rows, best remote row for each input row
• best-remote: Matched rows, best input row for each remote row
• each: One row per input row, contains best remote match or blank
• each-dist: One row per input row, column giving distance only for best match
Note only the all mode is symmetric between the two tables.

Note also that there is a bug in best-remote matching. If the match is done in multiple blocks, it's possible for a remote table row to appear matched against one local table row per uploaded block, rather than just once for the whole result. If you're worried about that, set blocksize >= rowCount. This may be fixed in a future release.

[Default: all]

fixcols = none|dups|all       (Fixer)
Determines how input columns are renamed before use in the output table. The choices are:
• none: columns are not renamed
• dups: columns which would otherwise have duplicate names in the output will be renamed to indicate which table they came from
• all: all columns will be renamed to indicate which table they came from
If columns are renamed, the new ones are determined by suffix* parameters.

[Default: dups]

icmd = <cmds>       (ProcessingStep[])
Specifies processing to be performed on the input table as specified by parameter in, before any other processing has taken place. 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.

ifmt = <in-format>       (String)
Specifies the format of the input table as specified by parameter in. 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)]

in = <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 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.
istream = true|false       (Boolean)
If set true, the input table specified by the in parameter will be read as a stream. It is necessary to give the ifmt 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]

maxrec = <int-value>       (Integer)
Limit to the number of rows resulting from this operation. If the value is negative (the default) no limit is imposed. Note however that there can be truncation of the result if the number of records returned from a single chunk exceeds the service hard limit (2,000,000 at time of writing).

[Default: -1]

ocmd = <cmds>       (ProcessingStep[])
Specifies processing to be performed on the output table, after all other processing has taken place. 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.

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.

This parameter must only be given if omode has its default value of "out".

[Default: (auto)]

omode = out|meta|stats|count|cgi|discard|topcat|samp|plastic|tosql|gui       (ProcessingMode)
The mode in which the result table will be output. The default mode is out, which means that the result will be written as a new table to disk or elsewhere, as determined by the out and ofmt parameters. However, there are other possibilities, which correspond to uses to which a table can be put other than outputting it, such as displaying metadata, calculating statistics, or populating a table in an SQL database. For some values of this parameter, additional parameters (<mode-args>) are required to determine the exact behaviour.

Possible values are

• out
• meta
• stats
• count
• cgi
• discard
• topcat
• samp
• plastic
• tosql
• gui
Use the help=omode flag or see Section 6.4 for more information.

[Default: out]

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.

This parameter must only be given if omode has its default value of "out".

[Default: -]

presort = true|false       (Boolean)
If true, the rows are sorted by HEALPix index before they are uploaded to the CDS X-Match service. If the match is done in multiple blocks, this may improve efficiency, since when matching against a large remote catalogue the X-Match service likes to process requests in which sources are grouped into a small region rather than scattered all over the sky.

Note this will have a couple of other side effects that may be undesirable: it will read all the input rows into the task at once, which may make it harder to assess progress, and it will affect the order of the rows in the output table.

It is probably only worth setting true for rather large (multi-million-row?) multi-block matches, where both local and remote catalogues are spread over a significant fraction of the sky. But feel free to experiment.

[Default: false]

ra = <expr>       (String)
Right ascension in degrees in the ICRS coordinate system for the position of each row of the input table. This may simply be a column name, or it may be an algebraic expression calculated from columns as explained in Section 10. If left blank, an attempt is made to guess from UCDs, column names and unit annotations what expression to use.
radius = <value/arcsec>       (Double)
Maximum distance from the local table (ra,dec) position at which counterparts from the remote table will be identified. This is a fixed value given in arcseconds, and must be in the range [0,180] (this limit is currently enforced by the CDS Xmatch service).
serviceurl = <url-value>       (URL)
The URL at which the CDS Xmatch service can be found. Normally this should not be altered from the default, but if other implementations of the same service are known, this parameter can be used to access them.

[Default: http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync]

suffixin = <label>       (String)
If the fixcols parameter is set so that input columns are renamed for insertion into the output table, this parameter determines how the renaming is done. It gives a suffix which is appended to all renamed columns from the input table.

[Default: _in]

suffixremote = <label>       (String)
If the fixcols parameter is set so that input columns are renamed for insertion into the output table, this parameter determines how the renaming is done. It gives a suffix which is appended to all renamed columns from the CDS result table.

[Default: _cds]

usemoc = true|false       (Boolean)
If true, first acquire a MOC coverage map from CDS, and use that to pre-filter rows before uploading them for matching. This should improve efficiency, but have no effect on the result.

[Default: true]

### B.2.2 Examples

Here are some examples of cdsskymatch:

stilts cdsskymatch cdstable=II/246/out find=all

Matches a local catalogue dr5qso.fits against the VizieR table II/246/out (the 2MASS Point Source Catalogue). The search radius is 1 arcsecond, and all 2MASS sources within the radius of each input source are returned.
stilts cdsskymatch cdstable=simbad find=best
blocksize=1000 icmd=progress omode=topcat

This finds the closest object in the SIMBAD database within 8.5 arcsec for each row of an input ASCII table. Uploads are done in blocks of 1,000 rows at a time, and progress is displayed on the console. When the match is complete, the result is sent directly to a running instance of TOPCAT.
stilts cdsskymatch in=3XMM_DR4cat_slim_v1.0.fits
icmd='select "SC_POSERR < 1 && SC_EXTENT == 0"'
cdstable=B/mk/mktypes
find=best suffixin=_XMM suffixremote=_MK fixcols=all
ocmd='select startsWith(spType_MK,\"G\")'
out=xmm_gtype.fits

This locates XMM-Newton point-like sources identified as being of spectral type G. It uses the 3XMM-DR4 XMM-Newton serendipitous source catalogue as input. The icmd filter selects the objects in that catalogue with well-defined point-like positions. It then matches them with Skiff's MK spectral classification catalogue (B/mk/mktypes in VizieR) and finally filters the result to include only those sources identified as being of spectral type G. Thanks to Ada Nebot (CDS) for this example.

## B.3 cone: Executes a Cone Search-like query

cone is a utility to execute one of the "Simple" positional DAL query operations on a remote server: Simple Cone Search, Simple Image Access (SIA) or Simple Spectral Access (SSA). The job it does is not very complicated: given a base URL for a service of one of these types and values for the central position and radius required, it assembles the query URL in the form required for the relevant protocol, retrieves the result of the query, and turns it into a table which can be operated on with the usual STILTS pipeline operations.

### B.3.1 Usage

The usage of cone is

   stilts <stilts-flags> cone serviceurl=<url-value> lon=<degrees>
skysys=icrs|fk5|fk4|galactic|supergalactic|ecliptic
servicetype=cone|ssa|sia1|sia2|sia verb=1|2|3
compress=true|false dataformat=<value>

If you don't have the stilts script installed, write "java -jar stilts.jar" instead of "stilts" - see Section 3. The available <stilts-flags> are listed in Section 2.1. For programmatic invocation, the Task class for this command is uk.ac.starlink.ttools.task.TableCone.

Parameter values are assigned on the command line as explained in Section 2.3. They are as follows:

compress = true|false       (Boolean)
If true, the service is requested to provide HTTP-level compression for the response stream (Accept-Encoding header is set to "gzip", see RFC 2616). This does not guarantee that compression will happen but if the service honours this request it may result in a smaller amount of network traffic at the expense of more processing on the server and client.

[Default: true]

dataformat = <value>       (String)
Indicates the format of data objects described in the returned table. The meaning of this is dependent on the value of the servicetype parameter:
• servicetype=cone: not used
• servicetype=ssa: gives the MIME type of spectra referenced in the output table, also special values "votable", "fits", "compliant", "graphic", "all", and others (value of the SSA FORMAT parameter).
• servicetype=sia1: gives the MIME type required for images/resources referenced in the output table, corresponding to the SIA FORMAT parameter. The special values "GRAPHIC" (all graphics formats) and "ALL" (no restriction) as defined by SIAv1 are also permissible. For SIA version 1 only, this defaults to"image/fits".
• servicetype=sia2: gives the MIME type required for images/resources referenced in the output table, corresponding to the SIA FORMAT parameter. The special values "GRAPHIC" (all graphics formats) and "ALL" (no restriction) as defined by SIAv1 are also permissible.
• servicetype=sia: gives the MIME type required for images/resources referenced in the output table, corresponding to the SIA FORMAT parameter. The special values "GRAPHIC" (all graphics formats) and "ALL" (no restriction) as defined by SIAv1 are also permissible. For SIA version 1 only, this defaults to"image/fits".
lat = <degrees>       (Double)
Central latitude position for cone search. By default this is the Declination, but depending on the value of the skysys parameter it may be in a different sky system.
lon = <degrees>       (Double)
Central longitude position for cone search. By default this is the Right Ascension, but depending on the value of the skysys parameter it may be in a different sky system.
radius = <degrees>       (Double)
servicetype = cone|ssa|sia1|sia2|sia       (ServiceType)
Selects the type of data access service to contact. Most commonly this will be the Cone Search service itself, but there are one or two other possibilities:
• cone: Cone Search protocol - returns a table of objects found near each location. See Cone Search standard.
• ssa: Simple Spectral Access protocol - returns a table of spectra near each location. See SSA standard.
• sia1: Simple Image Access protocol version 1 - returns a table of images near each location. See SIA 1.0 standard.
• sia2: Simple Image Access protocol version 2 - returns a table of images near each location. See SIA 2.0 standard.
• sia: alias for sia1

[Default: cone]

serviceurl = <url-value>       (URL)
The base part of a URL which defines the query to be made. Additional parameters will be appended to this using CGI syntax ("name=value", separated by '&' characters). If this value does not end in either a '?' or a '&', one will be added as appropriate.
skysys = icrs|fk5|fk4|galactic|supergalactic|ecliptic       (SkySystem)
Sky coordinate system used to interpret the lon and lat parameters. If the value is ICRS (the default) the provided values are assumed to be Right Ascension and Declination and are sent unchanged; for other values they will be converted from the named system into RA and Dec first.

[Default: icrs]

verb = 1|2|3       (String)
Verbosity level of the tables returned by the query service. A value of 1 indicates the bare minimum and 3 indicates all available information.

### B.3.2 Examples

Here are some examples of cone:

stilts cone serviceurl=http://gaia.ari.uni-heidelberg.de/cone/search

stilts cone serviceurl=http://gaia.ari.uni-heidelberg.de/cone/search