/usr/share/doc/stilts/sun256/jystilts.html is in stilts-doc 3.1.2-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 | <html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="sun-style.css">
<title>JyStilts - STILTS from Python</title>
</head>
<body>
<hr>
<a href="jyrun.html">Next</a> <a href="jdbcConfig.html">Previous</a> <a href="index.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="jyrun.html">Running JyStilts</a><br>
<b>Up: </b><a href="index.html">Top</a><br>
<b>Previous: </b><a href="jdbcConfig.html">JDBC Configuration</a><br>
<hr>
<hr>
<h2><a name="jystilts">4 JyStilts - STILTS from Python</a></h2>
<p>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.
</p>
<p>However, it is also possible to invoke STILTS commands from within
the <a href="http://www.jython.org/">Jython</a> environment.
Jython is a pure-java implementation of the widely-used
<a href="http://www.python.org/">Python</a> 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.
</p>
<p>This approach has several advantages over the conventional command-line
usage:
<ul>
<li>You can make use of python programming constructions like
loops, functions and variables
</li>
<li>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
</li>
<li>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
</li>
<li>Because of the previous point, there are separate read, filter,
processing and write commands, which means command lines can be
shorter and less confusing
</li>
<li>The java startup overhead (typically a couple of seconds) happens only
once when entering jython, not once for every STILTS command
</li>
</ul>
Note however that you will <em>not</em> 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
<a href="http://jnumerical.sourceforge.net/index.html">JNumeric</a> for some of the Numpy functionality from Jython.)
</p>
<p>Usage from jython has syntax which is similar to command-line STILTS,
but with a few changes.
The following functions are defined by JyStilts:
<ul>
<li>A function <code>tread</code>, which reads a table from a
file or URL and turns it into a table object in jython
</li>
<li>A table method <code>write</code> which takes a table object and
writes it to file
</li>
<li>A table method for each STILTS <a href="filterSteps.html">filter</a>
(e.g. <code>cmd_head</code>, <code>cmd_select</code>,
<code>cmd_addcol</code>)
</li>
<li>A table method for each STILTS <a href="outModes.html">output mode</a>
(e.g. <code>mode_out</code>, <code>mode_meta</code>,
<code>mode_samp</code>),
</li>
<li>A function for each STILTS <a href="cmdUsage.html">task</a>
(e.g. <code>tmatch2</code>, <code>tcat</code>, <code>plot2sky</code>)
</li>
<li>A number of table methods which make table objects integrate nicely into
the python environment
</li>
</ul>
Reasonably detailed documentation for these is provided in the
usual Python way ("<em>doc strings</em>"),
and can be accessed using the Python "<code>help</code>" command, however
for full documentation and examples you should refer to this document.
</p>
<p>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:
<ol>
<li>Reading one or more tables from file using
the <code>tread</code> function
</li>
<li>Perhaps filtering the input table(s) using one or more of the
<code>cmd_*</code> filter methods
</li>
<li>Performing core processing such as crossmatching</li>
<li>Perhaps filtering the result using one or more of the
<code>cmd_*</code> filter methods
</li>
<li>If running interactively, perhaps examining the intermediate results
using one of the <code>mode_*</code> output modes
</li>
<li>Writing the final result to a file using the <code>write</code> method
</li>
</ol>
</p>
<p>Here is an example command line invocation for crossmatching two tables:
<pre>
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
</pre>
and here is what it might look like in JyStilts:
<pre>
>>> 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')
</pre>
</p>
<p>When running interactively, it can be convenient to examine the intermediate
results before processing or writing as well, for instance:
<pre>
>>> 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 |
+--------+---------------+-----------+
</pre>
</p>
<p>More detail about how to run JyStilts and its usage
is given in the following subsections.
</p>
<ul>
<li><a href="jyrun.html">4.1 Running JyStilts</a></li>
<li><a href="sec4.2.html">4.2 Table I/O</a></li>
<li><a href="jytable.html">4.3 Table objects</a></li>
<li><a href="jyfilter.html">4.4 Table filter commands (<code>cmd_*</code>)</a></li>
<li><a href="jymode.html">4.5 Table output modes (<code>mode_*</code>)</a></li>
<li><a href="jytask.html">4.6 Tasks</a></li>
<li><a href="jyfuncs.html">4.7 Calculation Functions</a></li>
</ul>
<hr><a href="jyrun.html">Next</a> <a href="jdbcConfig.html">Previous</a> <a href="index.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="jyrun.html">Running JyStilts</a><br>
<b>Up: </b><a href="index.html">Top</a><br>
<b>Previous: </b><a href="jdbcConfig.html">JDBC Configuration</a><br>
<hr><i>STILTS - Starlink Tables Infrastructure Library Tool Set<br>Starlink User Note256<br>STILTS web page:
<a href="http://www.starlink.ac.uk/stilts/">http://www.starlink.ac.uk/stilts/</a><br>Author email:
<a href="mailto:m.b.taylor@bristol.ac.uk">m.b.taylor@bristol.ac.uk</a><br>Mailing list:
<a href="mailto:topcat-user@jiscmail.ac.uk">topcat-user@jiscmail.ac.uk</a><br></i></body>
</html>
|