TOPCAT - Tool for OPerations on Catalogues And Tables
Version 4.10

Starlink User Note 253
Mark Taylor
7 August 2024

Contents

• Abstract
• 1 Introduction
• 2 Quick Start Guide
• 3 Apparent Table
• 3.1 Row Subsets
• 3.1.1 Defining Subsets
• 3.2 Row Order
• 3.3 Column Set
• 4 Table I/O
• 4.1 Table Formats
• 4.1.1 Input Formats
• 4.1.1.1 FITS
• 4.1.1.2 Column-oriented FITS
• 4.1.1.3 VOTable
• 4.1.1.4 CDF
• 4.1.1.5 CSV
• 4.1.1.6 ECSV
• 4.1.1.7 ASCII
• 4.1.1.8 IPAC
• 4.1.1.9 PDS4
• 4.1.1.10 MRT
• 4.1.1.11 Parquet
• 4.1.1.12 HAPI
• 4.1.1.13 Feather
• 4.1.1.14 GBIN
• 4.1.1.15 TST
• 4.1.1.16 World Data Center
• 4.1.2 Output Formats
• 4.1.2.1 FITS
• 4.1.2.2 VOTable
• 4.1.2.3 CSV
• 4.1.2.4 ECSV
• 4.1.2.5 ASCII
• 4.1.2.6 IPAC
• 4.1.2.7 Parquet
• 4.1.2.8 Feather
• 4.1.2.9 Text
• 4.1.2.10 HTML
• 4.1.2.11 LaTeX
• 4.1.2.12 Tab-Separated Table
• 4.1.2.13 Mirage Format
• 4.1.3 Non-standard FITS conventions
• 4.1.3.1 FITS-plus
• 4.1.3.2 Wide FITS
• 4.1.4 Custom I/O Formats
• 4.2 Input Locations
• 4.3 Input Schemes
• 4.3.1 skysim
• 4.3.2 attractor
• 4.3.3 jdbc
• 4.3.4 loop
• 4.3.5 test
• 4.3.6 class
• 4.3.7 hapi
• 5 Joins and Matches
• 5.1 Concatenating Tables
• 5.2 Matching Rows Between Tables
• 5.3 Matching Rows Within a Table
• 5.4 Multi-Object Matches
• 5.5 Plotting Match Results
• 5.6 Notes on Matching
• 5.7 Matching against a Remote Table
• 6 Virtual Observatory Access
• 6.1 The Registry
• 6.2 Data Access Services
• 6.3 Authentication
• 7 Algebraic Expression Syntax
• 7.1 Referencing Cell Values
• 7.2 Referencing Row Subset Flags
• 7.3 Referencing Table Parameters
• 7.4 Special Tokens
• 7.5 Null Values
• 7.6 Operators
• 7.7 Functions
• 7.7.1 Technical Note
• 7.8 Instance Methods
• 7.9 Examples
• 7.10 Adding User-Defined Functions
• 8 Activation Actions
• 9 Tool Interoperability
• 9.1 SAMP control
• 9.2 PLASTIC control
• 9.3 Messages Transmitted
• 9.4 Messages Received
• 10 Invoking TOPCAT
• 10.1 TOPCAT Command-line Arguments
• 10.2 Java Options
• 10.2.1 Class Path
• 10.2.2 Memory Size
• 10.2.3 System properties
• 10.3 JDBC Configuration
• 10.4 Tips for Large Tables
• 10.5 Examples
• A TOPCAT Windows
• A.1 Common Window Features
• A.1.1 Toolbar
• A.1.2 Menus
• A.1.3 JTables
• A.1.4 Column Selector
• A.2 Control Window
• A.2.1 Table List
• A.2.2 Current Table Properties panel
• A.2.3 Memory Monitor
• A.2.4 SAMP Panel
• A.2.5 Toolbar Buttons
• A.2.6 Menu Items
• A.3 Table View Windows
• A.3.1 Data Window
• A.3.2 Parameters Window
• A.3.3 Columns Window
• A.3.4 Subsets Window
• A.3.5 Statistics Window
• A.3.6 DataLink Window
• A.4 Plot Windows
• A.4.1 Differences From Old-Style Plot Windows
• A.4.2 Plot Window Overview
• A.4.2.1 Navigation
• A.4.2.2 Table Data Layer Controls
• A.4.2.3 Defining Subsets Graphically
• A.4.2.3.1 Subset from Visible
• A.4.2.3.2 Algebraic Subset From Visible
• A.4.2.3.3 Draw Blob Subset
• A.4.2.3.4 Draw Algebraic Subset
• A.4.2.4 Distance Measurement
• A.4.2.5 Plot Export Window
• A.4.3 Fixed Controls
• A.4.3.1 Frame Control
• A.4.3.2 Legend Control
• A.4.3.3 Axes Control
• A.4.3.4 Stilts Control
• A.4.3.5 Aux Axis Control
• A.4.4 Layer Controls
• A.4.4.1 Position Layer Control
• A.4.4.2 Pair Position Layer Control
• A.4.4.3 Quad Position Layer Control
• A.4.4.4 Matrix Layer Control
• A.4.4.5 Healpix Layer Control
• A.4.4.6 Histogram Layer Control
• A.4.4.7 Area Layer Control
• A.4.4.8 Spectrogram Layer Control
• A.4.4.9 XYArray Layer Control
• A.4.4.10 Function Layer Control
• A.4.4.11 SkyGrid Layer Control
• A.4.4.12 SphereGrid Layer Control
• A.4.5 Plot Forms
• A.4.5.1 Mark Form
• A.4.5.2 Size Form
• A.4.5.3 SizeXY Form
• A.4.5.4 Vector Form
• A.4.5.5 SkyVector Form
• A.4.5.6 Error Bars Form
• A.4.5.7 XYEllipse Form
• A.4.5.8 SkyEllipse Form
• A.4.5.9 XYCorr Form
• A.4.5.10 SkyCorr Form
• A.4.5.11 Polygon Form
• A.4.5.12 Line Form
• A.4.5.13 Line3d Form
• A.4.5.14 Linear Fit Form
• A.4.5.15 Quantile Form
• A.4.5.16 Label Form
• A.4.5.17 Contour Form
• A.4.5.18 Grid Form
• A.4.5.19 SkyDensity Form
• A.4.5.20 Fill Form
• A.4.5.21 Histogram Form
• A.4.5.22 KDE Form
• A.4.5.23 KNN Form
• A.4.5.24 Densogram Form
• A.4.5.25 Gaussian Form
• A.4.5.26 Link2 Form
• A.4.5.27 Mark2 Form
• A.4.5.28 Poly4 Form
• A.4.5.29 Mark4 Form
• A.4.5.30 Area Form
• A.4.5.31 Central Form
• A.4.5.32 AreaLabel Form
• A.4.5.33 Lines Form
• A.4.5.34 Marks Form
• A.4.5.35 Handles Form
• A.4.5.36 YErrors Form
• A.4.5.37 XYErrors Form
• A.4.5.38 StatLine Form
• A.4.5.39 StatMark Form
• A.4.5.40 ArrayQuantile Form
• A.4.6 Shading Modes
• A.4.6.1 Flat Mode
• A.4.6.2 Translucent Mode
• A.4.6.3 Transparent Mode
• A.4.6.4 Auto Mode
• A.4.6.5 Density Mode
• A.4.6.6 Aux Mode
• A.4.6.7 Weighted Mode
• A.4.7 Colour Maps
• A.4.8 Histogram Plot Window
• A.4.8.1 Histogram Navigation
• A.4.8.2 Histogram Axes Control
• A.4.8.3 Bins Control
• A.4.9 Plane Plot Window
• A.4.9.1 Plane Navigation
• A.4.9.2 Plane Axes Control
• A.4.10 Sky Plot Window
• A.4.10.1 Sky Navigation
• A.4.10.2 Sky Axes Control
• A.4.11 Cube Plot Window
• A.4.11.1 Cube Navigation
• A.4.11.2 Cube Axes Control
• A.4.12 Sphere Plot Window
• A.4.12.1 Sphere Navigation
• A.4.12.2 Sphere Axes Control
• A.4.13 Corner Plot Window
• A.4.13.1 Corner Navigation
• A.4.13.2 Corner Axes Control
• A.4.14 Time Plot Window
• A.4.14.1 Plot Zones
• A.4.14.2 Time Navigation
• A.4.14.3 Time Axes Control
• A.5 Old-Style Plot Windows
• A.5.1 Common Features
• A.5.1.1 Dataset Selectors
• A.5.1.2 Axis Configuration and Zooming
• A.5.1.3 Error Bars
• A.5.1.4 Point Labels
• A.5.1.5 Auxiliary Axes
• A.5.1.6 Defining Subsets by Region
• A.5.1.7 Exporting Graphics
• A.5.2 Histogram (old-style)
• A.5.2.1 Histogram Style Editor
• A.5.3 2D Plot (old-style)
• A.5.3.1 Plot Style Editor
• A.5.4 Stacked Line Plot (old-style)
• A.5.4.1 Lines Style Editor
• A.5.5 3D Plot (old-style)
• A.5.5.1 3D Plot Style Editor
• A.5.6 Spherical Plot (old-style)
• A.5.7 Density Map (old-style)
• A.5.7.1 Density Style Editor
• A.6 Load Window
• A.6.1 Filestore Browser
• A.6.2 System Browser
• A.6.3 Hierarchy Browser
• A.6.3.1 Navigation
• A.6.3.2 Table Searches
• A.6.4 SQL Query
• A.6.5 Cone Search
• A.6.6 SIA Query
• A.6.7 SSA Query
• A.6.8 TAP Query
• A.6.9 VizieR Catalogue Service Query
• A.6.10 HAPI Query
• A.6.11 Virgo-Millennium Simulation Query
• A.6.12 BaSTI Theory Database Query
• A.6.13 Example Tables
• A.7 Save Window
• A.7.1 Content Panel
• A.7.1.1 Current Table
• A.7.1.2 Multiple Tables
• A.7.1.3 Session
• A.7.2 Destination Panel
• A.7.2.1 Enter Location
• A.7.2.2 Filestore Browser
• A.7.2.3 System Browser
• A.7.2.4 SQL Output Dialogue
• A.8 Match Windows
• A.8.1 Common Features
• A.8.1.1 Match Criteria
• A.8.1.2 Column Selection Boxes
• A.8.1.3 Tuning
• A.8.2 Pair Match Window
• A.8.2.1 Output Rows Selector Box
• A.8.3 Internal Match Window
• A.8.3.1 Internal Match Action Box
• A.8.4 Multiple Match Window
• A.8.4.1 Multiple Match Action Box
• A.9 VO Data Access Windows
• A.9.1 Common Features
• A.9.1.1 Registry Query Panel
• A.9.1.2 Single Positional Search Panel
• A.9.1.3 Multiple Positional Search Panel
• A.9.2 Cone Search
• A.9.3 Simple Image Access (SIA) Query
• A.9.4 Simple Spectral Access (SSA) Query
• A.9.5 Multiple Cone Search
• A.9.6 Multiple SIA Query
• A.9.7 Multiple SSA Query
• A.9.8 Table Access Protocol (TAP) Query
• A.9.8.1 Select Service tab
• A.9.8.2 Use Service tab
• A.9.8.3 Running Jobs tab
• A.9.8.4 Resume Job tab
• A.10 Activation Window
• A.10.1 Activation Actions
• A.10.1.1 Use Sky Coordinates in TOPCAT
• A.10.1.2 Send Sky Coordinates
• A.10.1.3 Display HiPS Cutout
• A.10.1.4 Send HiPS Cutout
• A.10.1.5 Display Image
• A.10.1.6 Display Image Region
• A.10.1.7 Send FITS Image
• A.10.1.8 Send Spectrum
• A.10.1.9 Send VOTable
• A.10.1.10 Send Row Index
• A.10.1.11 Load Table
• A.10.1.12 Plot Table
• A.10.1.13 View in Web Browser
• A.10.1.14 Download URL
• A.10.1.15 Delay
• A.10.1.16 Execute Code
• A.10.1.17 Run System Command
• A.10.1.18 SAMP Message
• A.10.1.19 Display Cutout Image
• A.10.1.20 Invoke Service
• A.10.1.21 Invoke Datalink Row
• A.10.1.22 View Datalink Table
• A.10.2 Viewer Windows
• A.10.2.1 Image Viewer Applications
• A.10.2.2 Spectrum Viewers
• A.10.2.3 Web Browsers
• A.10.3 Activation Security
• A.11 Other Windows
• A.11.1 CDS Upload X-Match Window
• A.11.2 Concatenation Window
• A.11.3 SAMP Window
• A.11.4 Help Window
• A.11.5 Column Search Window
• A.11.6 New Parameter Window
• A.11.7 Synthetic Column Window
• A.11.8 Sky Coordinates Window
• A.11.9 Algebraic Subset Window
• A.11.10 Multi Algebraic Subset Window
• A.11.11 Column Classification Window
• A.11.12 Available Functions Window
• A.11.13 Log Window
• B Algebraic Functions
• B.1 General Functions
• B.1.1 Arithmetic
• B.1.2 Arrays
• B.1.3 Bits
• B.1.4 Conversions
• B.1.5 CoordsDegrees
• B.1.6 CoordsRadians
• B.1.7 Coverage
• B.1.8 Distances
• B.1.9 Fluxes
• B.1.10 Formats
• B.1.11 Gaia
• B.1.12 KCorrections
• B.1.13 Lists
• B.1.14 Maths
• B.1.15 Randoms
• B.1.16 Shapes
• B.1.17 Sky
• B.1.18 Strings
• B.1.19 Tilings
• B.1.20 Times
• B.1.21 TrigDegrees
• B.1.22 URLs
• B.1.23 VO
• B.2 Activation Functions
• B.2.1 BasicImageDisplay
• B.2.2 Browsers
• B.2.3 Image
• B.2.4 Mgc
• B.2.5 Output
• B.2.6 Sdss
• B.2.7 SuperCosmos
• B.2.8 System
• B.2.9 TwoQZ
• C Release Notes
• C.1 Acknowledgements
• C.2 Version History