Next Previous Up Contents
Next: Table objects
Up: JyStilts - STILTS from Python
Previous: Running JyStilts

4.2 Table I/O

The tread function reads tables from an external location into JyStilts. Its arguments are as follows:

   tread(location, fmt='(auto)', random=False)
and its return value is a table object, which can be interrogated directly, or used in other JyStilts commands. Usually, the location argument should be a string which gives the filename or URL at which a table can be found. You can alternatively use a readable python file (or file-like) object for the location, but be aware that this may be less efficient on memory. As with command-line STILTS, the fmt argument is one of the options in Section 5.2.1, but may be left as the default if the format auto-detectable, which currently means if the file is in VOTable or FITS format. The random argument can be used to ensure that the returned file has random (i.e. not sequential-only) access; for some table formats the default way of reading them in means that their rows can only be accessed in sequence. Depending on what processing you are doing, that may or may not be satisfactory.

Examples of reading a table are:

   >>> import stilts
   >>> t1 = stilts.tread('cat.fits')
   >>> t2 = stilts.tread(open('cat.fits', 'rb'))           # less efficient
   >>> t3 = stilts.tread('data.csv', fmt='ascii', random=True)

The most straightforward way to write a table (presumably the result of one or a sequence of JyStilts commands) is using the write table method:

   write(self, location=None, fmt='(auto)')
The location gives either a string which is a filename, or a writable python file (or file-like) object. Again, use of a filename is preferred as it may(?) be more efficient. If no location is supplied, the table will be written to standard output (useful for inspection, but a bad idea for binary formats or very large tables). The fmt argument is one of the output formats in Section 5.2.2, but may be left as the default if the format can be guessed from the filename.

Examples of writing a table are:

   >>> table.write('out.fits')
   >>> table.write(open('out.fits', 'wb'))       #  less efficient?
   >>> table.write('catalogue.dat', fmt='csv')
   >>> table.write()                             #  display to stdout

Often it's convenient to combine examining the table with filtering steps, for instance:

   >>> table.every(100).write()
would write only every hundredth row, and
   >>> (table.cmd_sorthead(10, 'BMAG')
   ...       .cmd_select('!NULL_VMAG')
   ...       .cmd_keepcols('BMAG VMAG')
   ...       .write())
would write only the BMAG and VMAG columns for the ten rows in which VMAG is non-null with the lowest BMAG values.


Next Previous Up Contents
Next: Table objects
Up: JyStilts - STILTS from Python
Previous: Running JyStilts

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