TOPCAT - Tool for OPerations on Catalogues And Tables
Version 4.8-8
Starlink User Note 253
Mark Taylor
20 April 2023
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 Feather
4.1.1.13 GBIN
4.1.1.14 TST
4.1.1.15 World Data Center
4.1.2 Output Formats
4.1.2.1 FITS
4.1.2.2 Column-oriented FITS
4.1.2.3 VOTable
4.1.2.4 CSV
4.1.2.5 ECSV
4.1.2.6 ASCII
4.1.2.7 IPAC
4.1.2.8 Parquet
4.1.2.9 Feather
4.1.2.10 Text
4.1.2.11 HTML
4.1.2.12 LaTeX
4.1.2.13 Tab-Separated Table
4.1.2.14 Mirage Format
4.1.3 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
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
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 Healpix Layer Control
A.4.4.5 Histogram Layer Control
A.4.4.6 Area Layer Control
A.4.4.7 Spectrogram Layer Control
A.4.4.8 XYArray Layer Control
A.4.4.9 Function Layer Control
A.4.4.10 SkyGrid Layer Control
A.4.4.11 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 Time Plot Window
A.4.13.1 Plot Zones
A.4.13.2 Time Navigation
A.4.13.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 Virgo-Millennium Simulation Query
A.6.11 BaSTI Theory Database Query
A.6.12 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 Sog
B.2.8 SuperCosmos
B.2.9 System
B.2.10 TwoQZ
C Release Notes
C.1 Acknowledgements
C.2 Version History