TOPCAT - Tool for OPerations on Catalogues And Tables Version 4.8-1 Starlink User Note253 Mark Taylor 10 June 2021 Abstract TOPCAT is an interactive graphical viewer and editor for tabular data. It has been designed for use with astronomical tables such as object catalogues, but is not restricted to astronomical applications. It understands a number of different astronomically important formats, and more formats can be added. It is designed to cope well with large tables; a million rows by a hundred columns should not present a problem even with modest memory and CPU resources. It offers a variety of ways to view and analyse the data, including a browser for the cell data themselves, viewers for information about table and column metadata, tools for joining tables using flexible matching algorithms, and extensive 2- and 3-d visualisation facilities. Using a powerful and extensible Java-based expression language new columns can be defined and row subsets selected for separate analysis. Selecting a row can be configured to trigger an action, for instance displaying an image of the catalogue object in an external viewer. Table data and metadata can be edited and the resulting modified table can be written out in a wide range of output formats. A number of options are provided for loading data from external sources, including Virtual Observatory (VO) services, thus providing a gateway to many remote archives of astronomical data. It can also interoperate with other desktop tools using the SAMP protocol. TOPCAT is written in pure Java and is available under the GNU General Public Licence. Its underlying table processing facilities are provided by STIL, the Starlink Tables Infrastructure Library. Contents Abstract............................................................................................................................................. 1 1 Introduction................................................................................................................................ 10 2 Quick Start Guide....................................................................................................................... 12 3 Apparent Table........................................................................................................................... 14 3.1 Row Subsets.............................................................................................................................. 14 3.1.1 Defining Subsets.................................................................................................................... 15 3.2 Row Order................................................................................................................................. 16 3.3 Column Set................................................................................................................................ 16 4 Table I/O...................................................................................................................................... 18 4.1 Table Formats............................................................................................................................ 18 4.1.1 Input Formats......................................................................................................................... 18 4.1.1.1 FITS..................................................................................................................................... 18 4.1.1.2 Column-oriented FITS........................................................................................................ 19 4.1.1.3 VOTable.............................................................................................................................. 20 4.1.1.4 CDF..................................................................................................................................... 21 4.1.1.5 CSV..................................................................................................................................... 21 4.1.1.6 ECSV................................................................................................................................... 22 4.1.1.7 ASCII.................................................................................................................................. 23 4.1.1.8 IPAC.................................................................................................................................... 25 4.1.1.9 MRT.................................................................................................................................... 25 4.1.1.10 Parquet............................................................................................................................... 26 4.1.1.11 Feather............................................................................................................................... 27 4.1.1.12 GBIN................................................................................................................................. 28 4.1.1.13 TST.................................................................................................................................... 29 4.1.1.14 World Data Center............................................................................................................ 29 4.1.2 Output Formats....................................................................................................................... 30 4.1.2.1 FITS..................................................................................................................................... 30 4.1.2.2 Column-oriented FITS........................................................................................................ 31 4.1.2.3 VOTable.............................................................................................................................. 32 4.1.2.4 CSV..................................................................................................................................... 32 4.1.2.5 ECSV................................................................................................................................... 33 4.1.2.6 ASCII.................................................................................................................................. 34 4.1.2.7 IPAC.................................................................................................................................... 35 4.1.2.8 Parquet................................................................................................................................. 35 4.1.2.9 Feather................................................................................................................................. 36 4.1.2.10 Text.................................................................................................................................... 36 4.1.2.11 HTML................................................................................................................................ 37 4.1.2.12 LaTeX................................................................................................................................ 38 4.1.2.13 Tab-Separated Table......................................................................................................... 38 4.1.2.14 Mirage Format................................................................................................................... 39 4.1.3 Custom I/O Formats............................................................................................................... 39 4.2 Input Locations.......................................................................................................................... 40 4.3 Input Schemes........................................................................................................................... 41 4.3.1 skysim .................................................................................................................................... 41 4.3.2 attractor ...............................................................................................................................42 4.3.3 jdbc ........................................................................................................................................ 43 4.3.4 loop ........................................................................................................................................ 43 4.3.5 test ........................................................................................................................................ 44 4.3.6 class ...................................................................................................................................... 45 5 Joins and Matches...................................................................................................................... 46 5.1 Concatenating Tables................................................................................................................ 46 5.2 Matching Rows Between Tables............................................................................................... 46 5.3 Matching Rows Within a Table................................................................................................ 48 5.4 Multi-Object Matches............................................................................................................... 48 5.5 Plotting Match Results.............................................................................................................