TOPCAT Exercises


Some of the following may be useful:

Exercise 0: Run TOPCAT

  1. Java needs to be installed and on your path. Any non-ancient version should do. Download JRE from Oracle if necessary.
  2. Download topcat-full.jar (for Un*x, you can also download shell script topcat and put it with chmod +x in the same directory).
  3. Start it up: java -jar topcat-full.jar, or click on jar file, or run topcat shell script

Exercise 1: Visualisation

This exercise downloads some Tycho data with positions and proper motions from VizieR, views it in various ways in TOPCAT, identifies a co-moving group, and examines that in colour-magnitude space. Thanks to Niall Deacon from Hawaii for the basic idea.

Get Tycho data in region of Pleiades

  1. Open VizieR load dialogue: menu item VO|VizieR Catalogue Service
  2. In Row Selection panel:
  3. In Catalogue Selection panel:
  4. This should load some new tables I_259_* into TOPCAT. The most useful is I_259_tyc2. Select it by clicking on it in the list on the left of the control window.
    (If you can't get it working, use this one: tycho_pleiades.xml)
  5. Examine the table by looking at its data and metadata; toolbar buttons:

Plot the source positions on the sky

  1. Open a Sky Plot
  2. Ensure the right thing is chosen to plot in the Position tab:
  3. You should see a few hundred points in a circle (exact number displayed at bottom of screen).
  4. Zoom out and in (mouse wheel or Right-button-drag or CTRL-drag). Note zoom is around mouse position.
    See line at the bottom of the window for navigation help.
  5. Pan around (Left-button drag)
  6. Investigate Axes control Projection tab to change sky projection
  7. Use the Float Controls toolbar button if it fits your screen better

(Optional) Plot source proper motion vectors on the sky

  1. Ensure you have a Sky Plot and the Data control control is selected
  2. Click the Form tab
  3. Play with the Shape and Size selectors
  4. You already (by default) have a Mark control which plots a small square at each position.
  5. Now plot proper motion vectors at each position by clicking the button. See a new Vector control appear in the stack.
  6. This needs to know the vector components. Fill in the Proper Motion Longitude/Latitude fields with "pmRA" and "pmDE". See all the little arrows.
  7. You can turn the point markers and vectors on and off independently by clicking the checkboxes by the side of their controls in the stack.
  8. You can change the arrow sizes with the Scale slider.
  9. If you want to colour the arrows or points by direction:

Identify co-moving objects

  1. Open a Plane Plot
  2. In the Position tab:
  3. Zoom and pan to position the points where you can see them (navigation hints and help button are at the bottom of the screen)
  4. Observe two populations: most (not moving much) near (0,0), but a co-moving population clustered near (20,-45)
  5. Select the co-moving population:
  6. Observe the selected points have changed colour
  7. This is now a new Row Subset
  8. Open the Row Subsets window (from main window toolbar)
  9. There should be two subsets listed: All, and the one you just created. See how many rows the new one has (~200?)
  10. Add a complement set by clicking the new subset to select it and hitting the Invert Subset toolbar button
  11. Go to a plot (either one you've already done or a new one) and click the Subsets tab.
  12. Click the checkboxes to turn the different subsets (All, comoving, not_comoving) on and off. You can change the order they are plotted in (which shows on top) by dragging the drag handle up and down.

Plot colour magnitude diagram

  1. Open a Plane Plot
  2. In the Position tab:
  3. Reverse the Y axis:
  4. Return to Data control
  5. Select Subsets tab
  6. Make sure the comoving subset is plotted. See the comoving population tightly grouped in colour-magnitude space.

Optional: Send using SAMP

  1. If you have some other SAMP-aware tool running (e.g. ds9, Aladin) try hitting the Broadcast Table button. You can see which other SAMP tools TOPCAT is aware of (if any) in the bottom right panel of the main control window.
  2. If that worked, open the Row Subsets window , click on a row to highlight one of the subsets, and hit the Broadcast Row Subset button in that window to send the subset.
  3. Check Aladin is in Select mode . Then whenever you move the cursor over a point in Aladin, the same point will be highlighted in TOPCAT plots or the table viewer window .
  4. You can also check the Broadcast Row Subset checkbox in the main control window so that any time you highlight a row in TOPCAT it will get sent to other tools.

Exercise 2: Crossmatching

This exercise uses two datasets representing objects in the same region of sky. It performs a positional crossmatch, and uses the results to plot some different colours against each other.

Download data

  1. Use VizieR in the same region again menu item VO|VizieR Catalogue Service
  2. RA, Dec and Radius should be still filled in from last exercise, otherwise, go back and enter values
  3. Set Maximum Row Count to 100000 (2MASS-PSC has many sources, if you don't do this the result will be truncated)
  4. In Catalogue Selection panel, select By Keyword tab, and enter "2mass psc" in Keywords field, hit Search Catalogues button.
  5. Select II/246 and hit OK.
  6. This should load all the 2MASS point sources around the Pleiades - about 52,000 sources.
    (If you can't get it working, use this one: 2mass_pleiades.xml)

Crossmatch 2MASS PSC with Tycho

  1. Open Pair Match window, toolbar button
  2. Use the default value of Sky for the matching Algorithm
  3. Enter "3" (arcsec) in the Max Error field.
  4. For the Table 1 and Table 2 panels, fill them in with the table name and an RA/Dec pair for the Tycho and 2MASS tables respectively
  5. Select All Matches for the Match Selection
  6. Click Go

View the crossmatch result graphically

  1. When the match is complete, a popup window will give you the options OK or Plot Result . Select Plot Result.
  2. You should see a plot with three layers:
  3. Each located pair is represented by a grey dumbell shape. It will look like a grey circle at default magnification. Zoom right in to one of the pairs (mouse wheel/right-drag/ctrl-drag). You should be able to see that the positions are different.
  4. Experiment with the appearance of the layers - turn different layers on/off, change the size/shape/colour of the markers etc.

Do something useful with the result

Having determined associations between 2MASS PSC and Tycho objects you can make plots with some combination of 2MASS and Tycho columns, for instance:

  1. Colour-magnitude plot using IR and optical colours
  2. 3-d colour-colour-colour plot

Assess input match radius from the result

  1. Examine the columns in the output table ( toolbar button). The first lot are from the first input table, the second lot are from the second input table. The last column is special:
  2. Plot a histogram of the Separation column. A good way to zoom in histograms is with the mouse below or to the left of the plot axes (zooms one axis at a time). Can you tell from this which matches are spurious? What would have been a good value for the matching radius?
  3. You might want to define a Row Subset that uses only a sub-range of the separations you got so that you can throw out the spurious matches. A couple of ways to do that are: Or, you can re-do the match with the radius you want.

Find multiple matches in the result

  1. If you look back at the output table columns () you can see two more special columns near the end: GroupSize>=2 means more than one match was found (in this case, multiple 2MASS objects within the search radius of a given Tycho object).
  2. Try to identify these multi-object matches. Some ways to do that are: (If you can't see any multi-object matches: check that you used All Matches and not Best Match in the match window Match Selection field)
  3. When you can see one of these rows, in the table viewer window , click on it. That will highlight the row, and also paint a little target icon around that point on the plot of the match result. If you zoom in you should be able to see the multiple matches.
  4. If that's too much hard work, re-do the match with a much larger radius (e.g. 1 arcmin). It will be pretty obvious from the plotted result that some of the matches are multiple.


  1. Try to find a Tycho object which does not have a 2MASS counterpart. To do this, set Join Type to 1 not 2 (or 2 not 1, depending on what order you did the match in) in the Pair Match window, and run the match again. Note this option does not currently do the plot for you, but to see the result you can add the new table () to one of the existing match result plots, or build a plot up with the required layers from scratch.

Optional: Label points

  1. Click the Form tab associated with one of the Data controls for the Tycho catalogue.
  2. Now add labels to each point by clicking the button. See a new Label control appear in the stack.
  3. Tell it what label to write. Fill in the Text field with (say) recno.
  4. See the text labels appear. By default, you will only see the labels if they're not too crowded together, so you may need to zoom in to see them.

If you've got this far, you can play with your own data, take a break, or swot up for the ADQL/TAP exercise.

$Id: tcex.xhtml,v 1.10 2014/03/25 20:11:29 mbt Exp $