Next Previous Up Contents
Next: Running JyStilts
Up: Top
Previous: JDBC Configuration


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:

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:

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 = 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.


Next Previous Up Contents
Next: Running JyStilts
Up: Top
Previous: JDBC Configuration

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk