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

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

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

>>> import stilts
>>> t1 = stilts.tread('survey.fits')
>>> t1 = t1.cmd_addskycoords(t1, 'fk4', 'fk5', 'RA1950', 'DEC1950', 'RA2000', 'DEC2000')
>>> t2 = stilts.tread('mycat.csv', 'csv')
>>> 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
>>> tm.cmd_keepcols('ID ALPHA DELTA').cmd_head(4).write()
+--------+---------------+-----------+
| 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
• 4.2 Table I/O
• 4.3 Table objects
• 4.4 Table filter commands (cmd_*)
• 4.5 Table output modes (mode_*)
• 4.6 Tasks
• 4.7 Calculation Functions