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:
Usage from jython has syntax which is similar to command-line STILTS, but with a few changes. The following functions are defined by JyStilts:
tread, which reads a table from a file or URL and turns it into a table object in jython
writewhich takes a table object and writes it to file
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:
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.fitsand 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.