Catalogs

Displaying a Catalog

This thread uses an optical image of the Antennae Galaxies (NGC 4038/NGC 4039) from the Digital Sky Survey (DSS). It was retrieved via the "Analysis → Image Servers" menu in ds9.

A number of the most popular catalogs are listed by wavelength in the "Analysis → Catalogs" menu. More options can be accessed via the "Search for Catalogs" option in that menu.

First we overlay sources from 2MASS by choosing "Analysis → Catalogs → Infrared → 2MASS point sources". The source matches are displayed on the ds9 display (Figure 1) and listed in a "Catalog Tool" window (Figure 2).

Figure 1: 2MASS Sources for the Antennae Galaxies

A set area centered on the field of view is used for the first catalog search. The center and size of the search area may be adjusted in the Catalog Tool by setting the RA, Dec, height, and width fields. The "Coordinate" and "Size" menus may be used to set the units for those values (degrees/sexagesimal and degrees/arcmin/arcsec, respectively). After changing the values, click the "Retrieve" button to update the Catalog Tool.

Figure 2: Catalog Tool of 2MASS Sources

Note that ds9 attempts to select the correct (RA,Dec) columns from the catalog data file in order to display the sources. In some cases, the user will have to explicitly set the column names by using the drop-down menus in the Catalog Tool. In this example, ds9 correctly chose "_RAJ2000" and "_DEJ2000".

Selecting Sources with the Cursor

From the "Edit" menu in ds9, choose the "Catalog" cursor type. Clicking on a source in the ds9 display highlights the corresponding row in the Catalog Tool. Multiple sources may be selected by holding down the SHIFT key while clicking them.

Similarly, highlighting a row in the Catalog Tool will blink the source region in ds9. If the "Pan to" option in the Catalog Tool "Preferences" menu is checked, the ds9 display also centers on the chosen source. Mutiple rows may be selected by holding down the SHIFT or CTRL key while selecting them.

Displaying Multiple Catalogs

More than one catalog can be displayed in the same frame. By default, the sources are displayed as green circle points. The color and shape can be changed in the "Symbol" menu of the Catalog Tool to distinguish between the different catalogs.

In Figure 3, the Chandra Source Catalog has been added to the display (Analysis → Catalogs → High Energy → Chandra Source). The symbols for the CSC sources are set to red diamonds.

Figure 3: CSC and 2MASS Sources for the Antennae Galaxies

To toggle the display of each catalog, use the "Show Regions" option in the Catalog Tool "Preferences" menu.

Clearing Catalog Sources

Simply closing the Catalog Tool will not remove the sources from the display. It is necessary to choose "Clear" from the corresponding Catalog Tool.

To remove all the sources from the display, use "Analysis → Catalogs → Clear All".

For the rest of this thread, only the 2MASS sources will be used.

Sorting and Filtering

The source listing is sorted on position by default. A different column for sorting may be selected from the "Sort" menu in the Catalog Tool. Related checkboxes determine whether the results are listed in increasing or decreasing order. The Catalog Tool in Figure 4 is sorted on the "Jmag" column in decreasing order.

Figure 4: 2MASS Sources Sorted by Decreasing Jmag

The "Filter" field in the Catalog Tool is used to filter out specific rows from the source matches. A filter is conditional expression that is evaluated for each row of the catalog. The column name must be referenced with a dollar sign in the expression, e.g. "$_RAJ2000".

To select the sources with low Jmag values, the filter "$Jmag<14" is used. Click the "Filter" button to update the Catalog Tool and the ds9 display. The results are shown in Figure 5.

Figure 5: Filtering 2MASS Sources: Jmag<14

TCL expression syntax can be used to construct more complex filters. The filter "$Jmag<14 || $Jmag>16.5" uses the logical "OR" syntax ("||") to select any source with Jmag less than 14 or greater than 16.5, as shown in Figure 6.

Figure 6: Filtering 2MASS Sources: Jmag<14 or Jmag>16.5

The uniformity of the symbols doesn't distinguish between the low-Jmag sources and the high-Jmag sources. The advanced symbol editing in the next section improves on this display.

Before continuing the thread, clear the filter in the Catalog Tool so that all the sources are displayed.

Specifying Symbols with Conditional Expressions

The advanced symbol editing in the Catalog Tool allows you to specify the shape, size, color, and text of each symbol based on catalog column values.

Open the "Symbol Editor" from the "Symbol → Advanced..." menu in the Catalog Tool. A conditional statement, written in the TCL expression syntax, is entered in the "If" field. The styles that should be applied are set by the other fields (shape, color, text, etc.).

First, define a rule that sets the sources with Jmag<14 to be red boxcircle points. The completed form is shown in Figure 7. After clicking the "Apply" button, the ds9 display is updated (Figure 8).

Figure 7: Symbol Editing: Jmag<14 Rule

Figure 8: Symbol Editing: Jmag<14 Sources Displayed

The "Add" button in the Symbol Editor is used to create a new, empty form. The second rule is defined such that sources with Jmag>16.5 will be cyan diamonds. After clicking the "Apply" button again, the ds9 display is as shown in Figure 9.

Figure 9: Symbol Editing: Jmag>16.5 Sources Added

To edit an existing rule, highlight the rule in the Symbol Editor and adjust the parameters. In Figure 10, both rules have been updated so that the Text field is set to "$Jmag". This displays the Jmag column value next to the symbol (Figure 11).

Figure 10: Symbol Editing: Rule to Add a Label

Figure 11: Symbol Editing: Jmag Labels Displayed

The ds9 Reference Manual has further examples of symbol expressions.

The set of rules may be saved from the "File" menu in the Symbol Editor. The output for these rules looks like:

condition       shape   color   text    size    size2   units   angle
---------       -----   -----   ----    ----    -----   -----   -----
$Jmag<14        boxcircle point red     $Jmag                   physical
$Jmag>16.5      diamond point   cyan    $Jmag                   physical

The file can be loaded into a later ds9 session by opening the Symbol Editor and using the "File → Load" menu item. Note that the column names in the symbol rules may have to be updated in order to use them with a different catalog.

Saving the Sources: Catalog Files and Region Files

Saving a Catalog File

The contents of the Catalog Tool may be saved from the "File → Save" menu. If any filters are applied, the filtered output is saved in the catalog file.

ds9 supports three catalog formats: VOTable, Starbase, and tab-separated file. If the catalog file will be loaded back into ds9 in the future, any of the three formats may be chosen.

Saving the Sources in a Region File

The sources may also be converted to a ds9 region file for use in data analysis, e.g. spectra extraction or calculating sources counts.

Select "Copy to Regions" from the Catalog Tool "File" menu. Once the sources are converted to regions, individual ones may be selected and edited or deleted, if desired. Save the regions from the "Region → Save Regions..." menu.

Citing a Catalog in Publication

If you wish to use the source information in a publication, refer to the "Acknowledgment" item under the "File" menu in the Catalog Tool. For instance, the 2MASS acknowledgment reads:

Acknowledgments for CDS

This research has made use of the VizieR catalogue access tool, CDS,
Strasbourg, France. VizieR is a joint effort of CDS (Centre de Données 
astronomiques de Strasbourg) and ESA-ESRIN (Information Systems Division).