/usr/share/doc/stilts/sun256/jytable.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 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 | <html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="sun-style.css">
<title>Table objects</title>
</head>
<body>
<hr>
<a href="jyfilter.html">Next</a> <a href="sec4.2.html">Previous</a> <a href="jystilts.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="jyfilter.html">Table filter commands (cmd_*)</a><br>
<b>Up: </b><a href="jystilts.html">JyStilts - STILTS from Python</a><br>
<b>Previous: </b><a href="sec4.2.html">Table I/O</a><br>
<hr>
<h3><a name="jytable">4.3 Table objects</a></h3>
<p>The tables read by the <code>tread</code> function and produced
by operating on them within JyStilts have a number of methods
defined on them.
These are explained below.
</p>
<p>First, a number of special methods are defined which allow a table to
behave in python like a sequence of rows:
<dl>
<dt><strong><code>__iter__</code></strong></dt>
<dd>This special method means that the table can be treated as an
<em>iterable</em>, so that for instance
"<code>for row in table:</code>" will iterate over all rows.
</dd>
<dt><strong><code>__len__</code> <em>(random-access tables only)</em></strong></dt>
<dd>This special method means that you can use the expression
"<code>len(table)</code>" to count the number of rows.
This method is not available for tables with sequential access only.
</dd>
<dt><strong><code>__getitem__</code> <em>(random-access tables only)</em></strong></dt>
<dd>Returns a row at a given index in the table.
This special method means that you can use indexing expressions like
"<code>table[3]</code>" or <code>table[0:10]</code> to obtain the
row or rows corresponding to a given row index or slice.
This method is not available for tables with sequential access only.
</dd>
<dt><strong><code>__add__</code>, <code>__mul__</code>, <code>__rmul__</code></strong></dt>
<dd>These special methods allow the addition and multiplication
operators "<code>+</code>" and and "<code>*</code>" to be used with
the sense of concatenation.
Thus "<code>table1+table2</code>" will produce a new table with the
rows of <code>table1</code> followed by the rows of <code>table2</code>.
Note this will only work if both tables have compatible columns.
Similarly "<code>table*3</code>" would produce a table like
<code>table</code> but with all its rows repeated three times.
</dd>
</dl>
In all of these cases, each row object that is accessed is a tuple
of the column values for that row of the table.
The tuple items (table cells) may be accessed using a key which is
a numeric index or slice in the usual way,
or with a key which is a column name, or one of the ColumnInfo objects
returned by <code>columns()</code>.
</p>
<p>Sometimes, the result of a table operation will be a table which
does not have random access. For such tables you can iterate over
the rows, but not get their row values by indexing.
Non-random-access tables are also peculiar in that <code>getRowCount</code>
returns a negative value.
To take a table which may not have random access and make it capable
of random access, use the <a href="random.html"><code>random</code></a>
filter: "<code>table=table.cmd_random()</code>".
</p>
<p>To a large extent it is possible to duplicate the functions of the
various STILTS commands by writing your own python code based on these
python-friendly table access methods.
Note however that such python-based processing is likely to be
<em>much</em> slower than the STILTS equivalents.
If performance is important to you, you should try in most cases
to use the various <code>cmd_*</code> commands etc for table processing.
</p>
<p>Second, some additional utility methods are defined:
<dl>
<dt><strong><code>count_rows()</code></strong></dt>
<dd>Returns the number of rows in the table in the most efficient
way possible. If the table is random-access or otherwise knows
its row count without further calculation, that value is returned.
Otherwise, the rows are iterated over without reading, which may take
some time but should be much more efficient than iterating over
the table as an iterable, since the row cell data itself is not
retrieved.
</dd>
<dt><strong><code>columns()</code></strong></dt>
<dd>Returns a tuple of the column descriptors for the table.
Each item in the tuple is an instance of the
<a href="http://www.starlink.ac.uk/stil/javadocs/uk/ac/starlink/table/ColumnInfo.html">ColumnInfo</a> class;
useful methods include <code>getName()</code>,
<code>getUnitString()</code>, <code>getUCD()</code>.
<code>str(column)</code> will return its name.
</dd>
<dt><strong><code>coldata(key)</code></strong></dt>
<dd>Returns a sequence of the values for the given column.
The sequence will have the same number of elements as the number of rows
in the table. The <code>key</code> argument may be either an integer
column index (if negative, counts backwards from the end),
or the column name or info object.
The returned value will always be iterable (has <code>__iter__</code>),
but will only be indexable
(has <code>__len__</code> and <code>__getitem__</code>) if the table
is random access.
</dd>
<dt><strong><code>parameters()</code></strong></dt>
<dd>Returns a name to value mapping of the table parameters
(per-table metadata).
This does not include all the available information about those
parameters, for instance unit and UCD information is not included.
For more detailed information, use the <code>StarTable</code> methods.
Note that as currently implemented, changing the values in the
returned mapping will not change the actual table parameter values.
</dd>
<dt><strong><code>write(location=None, fmt=None)</code></strong></dt>
<dd>Outputs the table.
The optional <code>location</code> argument gives a filename
or writable file object,
and the optional <code>fmt</code> argument gives a format, one of
the options listed in <a href="inFormats.html">Section 5.2.1</a>.
If <code>location</code> is not supplied, output is to standard output,
so in an interactive session it will be printed to the terminal.
If <code>fmt</code> is not supplied, an attempt will be made to guess
a suitable format based on the location.
</dd>
</dl>
</p>
<p>Third, a set of <code>cmd_*</code> methods corresponding to the
STILTS filters are available;
these are described in <a href="jyfilter.html">Section 4.4</a>.
</p>
<p>Fourth, a set of <code>mode_*</code> methods corresponding to the
STILTS output modes are available;
these are described in <a href="jymode.html">Section 4.5</a>.
</p>
<p>Finally, tables are also instances of the
<a href="http://www.starlink.ac.uk/stil/javadocs/uk/ac/starlink/table/StarTable.html">StarTable</a>
interface defined by
<a href="http://www.starlink.ac.uk/stil/">STIL</a>,
which is the table I/O layer underlying STILTS.
The full documentation can be found in the user manual and javadocs
on the STIL page, and all the java methods can be used from JyStilts,
but in most cases there are more pythonic equivalents provided,
as described above.
</p>
<p>Here are some examples of these methods in use:
<pre>
>>> import stilts
>>> xsc = stilts.tread('/data/table/2mass_xsc.xml') # read table
>>> xsc.mode_count() # show rows/column count
columns: 6 rows: 1646844
>>> print xsc.columns() # full info on columns
(id(String), ra(Double)/degrees, dec(Double)/degrees, jmag(Double)/mag, hmag(Double)/mag, kmag(Double)/mag)
>>> print [str(col) for col in xsc.columns()] # column names only
['id', 'ra', 'dec', 'jmag', 'hmag', 'kmag']
>>> row = xsc[1000000] # examine millionth row
>>> print row
(u'19433000+4003190', 295.875, 40.055286, 14.449, 13.906, 13.374)
>>> print row[0] # cell by index
19433000+4003190
>>> print row['ra'], row['dec'] # cells by col name
295.875 40.055286
>>> print len(xsc) # count rows, maybe slow
1646844
>>> print xsc.count_rows() # count rows efficiently
1646844L
>>> print (xsc+xsc).count_rows() # concatenate
3293688L
>>> print (xsc*10000).count_rows()
16468440000L
>>> for row in xsc: # select rows using python commands
... if row[4] - row[3] > 3.0:
... print row[0]
...
11165243+2925509
20491597+5119089
04330238+0858101
01182715-1013248
11244075+5218078
>>> # same thing using stilts (50x faster)
>>> (xsc.cmd_select('hmag - jmag > 3.0')
... .cmd_keepcols('id')
... .write())
+------------------+
| id |
+------------------+
| 11165243+2925509 |
| 20491597+5119089 |
| 04330238+0858101 |
| 01182715-1013248 |
| 11244075+5218078 |
+------------------+
</pre>
</p>
<p>The following are all ways to obtain the value of a given cell
in the table from the previous example.
<pre>
xsc.getCell(99, 0)
xsc[99][0]
xsc[99]['id']
xsc.coldata(0)[99]
xsc.coldata('id')[99]
</pre>
Some of these methods may be more efficient than others.
Note that none of these methods will work if the table has sequential-only
access.
</p>
<hr><a href="jyfilter.html">Next</a> <a href="sec4.2.html">Previous</a> <a href="jystilts.html">Up</a> <a href="index.html">Contents</a> <br> <b>Next: </b><a href="jyfilter.html">Table filter commands (cmd_*)</a><br>
<b>Up: </b><a href="jystilts.html">JyStilts - STILTS from Python</a><br>
<b>Previous: </b><a href="sec4.2.html">Table I/O</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>
|