liminfo

TOPCAT Reference

Free reference guide: TOPCAT Reference

26 results

About TOPCAT Reference

The TOPCAT Reference is a practical guide for astronomers and astrophysicists working with large astronomical catalogs. TOPCAT (Tool for OPerations on Catalogues And Tables) is a Java-based interactive graphical tool for tabular data analysis, and this reference covers its five core capability areas: Basic Usage (launching, file formats, stilts CLI, activation actions, export), Table Operations (column algebra, row subsets, sorting, statistics, JEL expression syntax), Visualization (sky plots, histograms, scatter plots, 3D cube plots, density plots, form layers), Cross-matching (sky position matching, exact value matching, internal duplicate detection, multi-table matching), and VO Services (CDS upload X-match, TAP/ADQL queries, cone search, SIA image access, SAMP interoperability).

The table operations section details how to create derived columns using JEL expressions (e.g., computing angular separations with skyDistanceDegrees, calculating magnitudes with log10, building color indices), define row subsets with boolean conditions for filtering by magnitude, classification, or signal-to-noise ratio, and compute per-column statistics including mean, median, standard deviation, and quantiles. The visualization section covers sky coordinate plotting with Aitoff and stereographic projections, density maps for million-point datasets, error bars, contour overlays, and variable-mapped point sizes and colors.

The cross-matching and VO services sections are particularly valuable for multi-wavelength astronomy. Sky cross-matching uses HEALPix indexing for efficient positional matching between catalogs with configurable match radius (typically 1 arcsecond). TAP queries enable direct access to remote databases like Gaia DR3 using ADQL (SQL extension with spatial functions like CONTAINS, POINT, CIRCLE). CDS upload X-match allows server-side matching against major catalogs (2MASS, SDSS, Gaia), while SAMP integration enables real-time data exchange with Aladin and DS9.

Key Features

  • Support for FITS, VOTable, CSV, TSV, ASCII, IPAC, and SQL database file formats for catalog I/O
  • JEL expression engine for computed columns with math, string, coordinate, and conditional functions
  • Sky plot visualization with Aitoff, stereographic, and sin projections for RA/Dec source distributions
  • Sky position cross-matching with configurable radius, HEALPix indexing, and best-match or all-match modes
  • TAP query interface for remote databases with ADQL spatial functions (CONTAINS, POINT, CIRCLE)
  • CDS upload X-match for server-side matching against 2MASS, SDSS, Gaia, and VizieR catalogs
  • SAMP protocol integration for real-time data exchange with Aladin, DS9, and other VO applications
  • stilts command-line interface for batch processing, scripted cross-matching, and automated plot generation

Frequently Asked Questions

What is TOPCAT used for in astronomy?

TOPCAT is an interactive Java application for exploring, analyzing, and cross-matching tabular astronomical data. It handles catalogs with millions of rows in formats like FITS and VOTable, provides interactive plotting (sky maps, scatter plots, histograms), enables cross-matching between catalogs by sky position or exact value, and connects to Virtual Observatory services for remote catalog queries. It is widely used for multi-wavelength catalog analysis and source identification.

How do I cross-match two astronomical catalogs by position?

Go to Joins > Sky Match, select the two tables, specify the RA and Dec columns for each, and set the match radius (typically 1 arcsecond). Choose Best Match for the closest single match per source, or All Matches for every pair within the radius. TOPCAT uses HEALPix spatial indexing for efficient matching even with millions of sources. The result separates matched and unmatched rows.

What is a TAP query and how do I use ADQL?

TAP (Table Access Protocol) allows querying remote astronomical databases using ADQL (Astronomical Data Query Language), an SQL extension with spatial functions. In TOPCAT, go to VO > TAP Query, enter a service URL (e.g., https://gea.esac.esa.int/tap-server/tap for Gaia), and write ADQL queries using functions like CONTAINS(POINT(ra,dec), CIRCLE(center_ra, center_dec, radius)) for cone searches.

How do I create computed columns in TOPCAT?

Use the Add Column function and enter a JEL expression. Examples include: sqrt(pow(ra1-ra2,2)+pow(dec1-dec2,2)) for coordinate differences, 2.5*log10(flux) for magnitude conversion, skyDistanceDegrees(ra1,dec1,ra2,dec2) for angular separation, and conditional expressions like condition ? val1 : val2. NULL values can be checked with isNull(x).

What is the difference between TOPCAT and stilts?

TOPCAT is the interactive GUI application for visual exploration and analysis. stilts (STIL Tool Set) is its command-line counterpart for batch processing and scripting. stilts commands like tpipe (table pipeline with filtering), tmatch2 (pairwise cross-matching), and plot2sky (sky plot export) can automate workflows that would be repetitive in the GUI. Both share the same underlying library.

How do I use CDS Upload X-match?

Go to VO > CDS Upload X-Match. Your local table is uploaded to the CDS server and matched against a selected remote catalog (2MASS, SDSS, WISE, Gaia, etc.) using positional matching. This is efficient for matching your sources against very large catalogs because the heavy computation happens server-side. Results are returned as a new table with combined columns from both catalogs.

What visualization options does TOPCAT offer?

TOPCAT provides sky plots (RA/Dec with Aitoff, stereographic, or sin projections), 2D scatter plots (plane plots with contour overlays), histograms (with log axes and subset coloring), 3D cube plots (with rotation and zoom), and density plots (pixel-based for millions of points with log-scale colormaps). Each plot supports multiple form layers including marks, lines, error bars, text labels, and variable-mapped sizes and colors.

How does SAMP integration work?

SAMP (Simple Application Messaging Protocol) enables TOPCAT to exchange data with other VO-compatible applications like Aladin (image viewer) and DS9 (FITS viewer) in real time. When you click a source in TOPCAT, its coordinates can be sent to Aladin to center the image view. Tables and images can be broadcast between applications. TOPCAT automatically starts a SAMP Hub when needed via Interop > SAMP.