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:

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

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