TOPCAT Tutorial

Resources

Sections

Basic Usage
Exercise: Add metadata to table
Plotting
Exercise: Pleiades
Exercise: Pleides revisited
Virtual Observatory
Exercise: ULX
Exercise: Chamaeleon

Basic Usage: Tables, Data and Metadata

Getting Started

Start TOPCAT (click on a jar file, or from the command line type

    topcat

    java -jar topcat-full.jar

or maybe

    topcat -Xmx512M

    java -Xmx512M -jar topcat-full.jar

Control Window

Use the Help window (). Search for a topic by entering words in the Find box. Other help options are in the Help menu. Or, use the manual from the TOPCAT web page.
Load an example table:
- Open load window ()
- Use Examples|Load Example Table menu item
Hover over toolbar buttons to see tool tips.
Click on menu bar and move over each menu to see available options. Note that some of these appear in the toolbar and others don't.
Examine basic table metadata in Control Window (Label, Name, Row count, Column count)
Edit the Label

Look at basic table data and metadata by using the items in the Views menu (or equivalent toolbar buttons). Choose a table with some metadata, e.g. the example table 6dfgs_mini (from Examples|Load Example Table menu in Load Window). Other FITS or VOTable tables (especially from Virtual Observatory sources) may have useful metadata; ASCII and CSV tables probably will not.

Data View

Scroll around
Move columns by dragging on column headers
Edit table data by double-clicking on cells
Sort by column by right-clicking on column in the table

Table Parameters (per-table metadata)

See metadata items.
Click on a row to see more detail.
Edit parameters by selecting them and changing the values in the detail panel below
Add and remove parameters using and .

Column Metadata

Open data viewer window () at the same time
Hide all columns () - see them disappear from the data viewer.
Select ones you're interested in by clicking the checkboxes in the Visible column - see them reappear in the data viewer.
Add a new column () - e.g. Name=B_R
- Name = B_R
- Expression = BMAG - RMAG
- Units = mag (optional)
See the column appear in the columns window, and the data viewer.
Edit the expression by double-clicking on it in the Expression column
Add new sky coordinate columns ()
- Select input System, Units and coordinate RA/Dec columns (e.g. ICRS, degrees, RA2000, J2000)
- Select output System and Units
- Either accept or edit suggested output column names
- Click OK
- See new columns appear in Column and Data Viewer windows

Table Subsets (row selections)

Use a table with some metadata, e.g. the example table 6dfgs_mini (from Examples|Load Example Table menu in Load Window).

View existing subsets, see how many rows they contain. These (if any) correspond to boolean (true/false) columns in the table as loaded; true values are included in the subset and false ones are not.
Add a subset ()
- Fill in the Subset Name field (e.g. blue_objs)
- Fill in the Expression field with an expression based on column names that evaluates to true or false (e.g. BMAG - RMAG < -1)
- See how many objects are in it (Size/Fraction columns in window)
- Edit expression by double-clicking it
- Add a new subset that is the inverse of the one you've added: select its row in the dispaly, then click

Table Statistics

See Mean, Standard Deviation, Minimum, Maximum etc.
Select other univariate stats from the Display menu
Use the Subset for calculations selector at the bottom of the window to choose which rows are calculated for

Apparent Table

Back in the Control Window, select a Row Subset which is not All. Note the Rows indicator shows Apparent rows accordingly.
Make sure some columns are hidden in the Column Window. Note the Columns indicator shows Apparent columns accordingly.
Select the Sort Order to sort the columns by a given column.
Look at the table in the Data Viewer - only the selected rows and columns are there, in the selected order.
If you Save the table now, that is what will get saved.
Duplicate the table using the File|Duplicate Table menu item. This is equivalent to saving the table and reloading it. Non-apparent rows and columns have disappeared in this copy.

Load Window

Open the Load Window
Look at the different toolbar buttons - lots of places to load a table from
Try a normal file browser to look for tables on your local filesystem.
- Filestore Browser usually suitable
- System Browser may be preferred for MacOS/Windows
- Format selector:
  - (auto) is OK for FITS and VOTable files
  - Need to select explicitly for ASCII, CSV, etc
Pin the window if you don't want it to close when you've loaded a table.
Or, type a URL or filename into the Location field, e.g.:
```
    ../data/messier.xml
    
```
Or, cut'n'paste a URL or filename onto the Table List in the Control Window.
To load multiple files from the same place, pin the window open, and double-click on the ones you want.
Hierarchical browser can look inside tar files, zip files, Multi-Extension FITS, multi-table VOTables, etc. If you have suitable files on your disk investigate them; otherwise try the Examples|Brows Demo Data menu item.
VizieR load dialog can download data direct from VizieR.
- If window is too tall for your screen, resize it and use the File|Scrollable option (present on all windows)
- Load supernova catalogue:
  1. Check All Rows radio button
  2. Choose By Keyword tab
  3. Enter "Asiago" in Keywords field
  4. Click Search Catalogues button
  5. Select first row (B/sn)
  6. Click the OK button at the bottom
  7. Table loads in TOPCAT
- Search for 2MASS extended sources:
  1. Click Cone Selection radio button
  2. Enter your favourite object name
  3. Click Resolve to get coordinates - RA and Dec fields are filled in
  4. Enter a suitable radius (1 degree?) make sure units selector is set correctly
  5. Choose Surveys tab
  6. Select 2MASX
  7. Table loads in TOPCAT
Millennium simulation database query.
- Default URL is for public database, no password required
- Choose MyMillennium3 from Base URL selector if preferred (password required)
- Use one of the examples in the HaloSamples or GalaxySamples menus and click OK
- ... or enter your own SQL.

Save Window

Select a table in the Control Window table list.
Open save window
Use Filestore Browser or System Browser to save it.
Choose an output format:
- If in doubt, choose FITS (most efficient, stores metadata)
- ASCII/CSV is OK if you want to process with other software
- Various other options are available ... see the manual for details
- TOPCAT will choose a sensible format if you use a well-known file extension like ".fits", ".csv", ".txt"
To save multiple tables in one file, use Multiple Tables tab (FITS/VOTable only)
To save session, use Save Session tab; this saves subsets and hidden columns, not just apparent tables

Exercise: Add metadata to table

Load a text table into TOPCAT, add column names and descriptions and table parameters, and save it as a FITS file.

TOPCAT has two main text-based formats for tables:

ASCII (see ASCII file details); don't forget to select ASCII format when loading it.
Comma-Separated Values (see CSV file details); don't forget to select CSV format when loading it.

If you strip out all the column headings, you should be able to load the table, but it will have column names like "col1", "col2" etc.

Use the ASCII file extracted.txt, or one of your own.

Load the table selecting Table Format as "ASCII" (or "CSV" if appropriate)
Check the column data types look OK (Class column in Columns window ), e.g. numeric columns should not have String type
Make sure the columns have sensible names. Either:
- Edit the column names by double-clicking on them in the Columns window
Or:
- Add a new header line in the ASCII file before loading it
Add some units and/or descriptions in the Columns window
Add some per-table metadata (e.g. author, date) in the Parameters window
Add some more calculated columns if you like
Save the table as a FITS or VOTable file
Reload it to check that the metadata is still there present

Plotting

Open Scatter Plot
Do a colour-magnitude plot for table 6dfgs_mini:
- X Axis BMAG-RMAG, Y Axis RMAG
- Select Flip checkbox for Y axis.
- Plot and unplot different subsets
- Use different plotting styles (click on plot symbols in Row Subsets panel, and/or Marker Style menu
- Add error bars ( and/or , or Errors menu)
- Change error styles (click on plot symbols in Row Subsets panel, and/or Error Style menu
- Make a new subset by selecting some of the points in the plot (click ; drag out a region or regions, click again)
- Experiment with Auxiliary Axes ()
- Try adding text labels ()
- Try the other plot types; there are some example tables here.
  - histogram (try weighting values )
  - Cartesian 3d plot
  - Spherical 3d plot (try adding radial coords )
  - Stacked line plot
  - Density plot (needs a large data set)

Exercise: Pleiades

(Credit: Niall Deacon, Hawaii)

Open the VizieR load dialog ()
Search for all the objects within 3 degrees of the Pleiades in the Tycho-2 catalogue:
- Check Cone Selection button
- Object name Pleiades, Resolve
- Radius 3 degrees
- Catalogue Selection Surveys tab
- Click on row Tycho-2 (Name column is ordered alphabetically)
- Click OK
- Loads 2 tables (2 tables in VizieR under that heading) - pick the one with most rows
Visualise proper motions:
- Open a scatter plot window
- X = pmRA, Y = pmDE
- Zoom in to find a cluster with non-zero motion
- Draw a blob round it to create a new subset (click ; drag out the cluster region, click again)
Draw colour-magnitude diagram:
- Open a different scatter plot window
- X = VTmag - BTmag, Y = VTmag, flip Y
- See where the new cluster subset you identified sit in colour-magnitude space (main sequence?).
Save the cluster identification:
- Go to the Subsets window
- Select the row corresponding to the cluster subset
- Create a new boolean table corresponding to this subset by clicking the To Column toolbar button
- Save the table.

Exercise: Pleiades revisited

Examine some other colours for the Pleiades cluster you identified in the previous exercise.

Reload the table from the previous exercise.
Select the cluster subset as the Current Row Subset in the Control Window. This will have the effect that subsequent matches only operate on these objects.
Go back to the VizieR load window , query a catalogue with different photometry in the same region
Crossmatch the (now subsetted) Tycho-2 catalogue with this new catalogue . You probably want Algorithm Sky with a suitable Max Error, and Match Selection Best Match Only, but if the resolutions of the different catalogues are significantly different, some other choice might be appropriate.
Visualise the positions of the crossmatch by overplotting the three sets of positions in the Spherical Plot window :
1. Input cluster positions
2. Positions loaded from VizieR catalogue(s)
3. Results of crossmatch
Overplot multiple data sets using use MarkerStyle menu to chose suitable symbol sets. Check the results look sensible.
Using the resulting cross-matched table, do a different colour magnitude diagram of the cluster objects.

Virtual Observatory

Multiple Simple Spectral Access Query

Get the Asiago catalogue of supernovae from the Vizier load window - click the All Rows radio button, search for "supernovae asiago" in the By Keyword tab, select "B/sn" and hit OK.
Look at the table - observe the Type column.
Create a new subset in the Subsets window - Name = 'type2', Expression = 'startsWith(type, "II")'.
Set this subset as the current Row Subset in the control window; this means that subsequent operations like the multi-SSA query will only operate on that subset.
Do an SSA multicone query from the VO or Joins menus on the main control window. Select a service, e.g. HST Spectra (either search by Keywords for "hst mast" or similar, or just find it in the list of services that appears automatically, perhaps by sorting the list which you can do by clicking on the appropriate column headers).
When you've clicked the service, fill in the parameters at the bottom of the window: Input Table is the SN catalogue, and make sure the RA and Dec selectors are filled in appropriately. You can leave radius blank if you like; for SSA this is interpreted by the server as asking for spectra that cover the position given.
Hit Go and wait for it to announce that it's added a new table. This is a table of all the HST spectra for type II supernovae from the B/sn catalogue.
Work out the age of each supernova when the spectrum was taken. Add a new column "obs_age" ( in window) with this expression:
```
    mjdToDecYear(isoToMjd(obs_start_time)) - (parseInt(substring(SN, 0, 4)))
    
```
(see the functions window for documentation). Note however this is only approximate, since the Asiago catalogue only gives you an age to the year.
Create a new subset with obs_age>=0.
Plot them on a sky plot - colour them by age and label them by ID .
Start up a spectrum viewer such as SPLAT (here is a link for splat WebStart).
Make sure a SAMP hub is running , . Observe in the control window that TOPCAT can see SPLAT
Set an Activation Action for the SN spectra table; click the Activation Action button in the control window, select View URL as Spectrum. Ensure that the Spectrum Location Column is filled in as the column which contains the spectrum URL (TOPCAT should fill this in automatically from examining column UTypes/UCDs - it's AcRef for the ST-ECF/HST/SSA service). You must then hit the OK button at the bottom of the window.
Click on one of the points in the spherical plot. It will cause the corresponding spectrum to be displayed in SPLAT.

Exercise: Ultra-Luminous X-ray sources

(Credit: M Perez-Torres, Paolo Padovani, Evanthia Hatziminaoglou, ESO)

See Euro-VO case described at http://www.euro-vo.org/pub/fc/workflows/ULX.html. Most of the things described here as being done with Aladin can equally be done with TOPCAT; the exception is the (optional) visualisation of the images.

Exercise: Chamaeleon Cluster

(Credit: Simon Murphy, ANU)

See script at http://www.mso.anu.edu.au/~murphysj/topcat/TOPCATtutorial.pdf.