The VAO Data Discovery Tool

Version 1.1.1, 2012-Jan-24

Introduction
Initiating a search
Exploring search results
Refining the results with filters
Retrieving Results
Tips & Notes

The Data Discovery Tool (DDT) is a web application for discovering all resources that are known to the VAO about an astrophysical object or a region of sky. The DDT provides the ability to select discovered resources by type (images, catalogs, web sites, etc.), passband, and many other criteria, and to explore or download them to your desktop.


Fig. 1—Anatomy of the Data Discovery Tool as it appears prior to the first search. Circled numbers in red are keyed to descriptions in the text.

The initial screen layout consists of the following components, numbered as in Fig. 1:

1. Search entry box: Enter an object name or sky coordinates. You may populate the entry field by typing in it or clicking the example text below the box.
2. Radius entry box: Enter a positive value to search within a circle centered on the object/position. Note: Maximum search radius is 2°.
3. Search results panel: A table of resources that match the search parameters will appear in this panel.
4. Filter facets panel: Applicable filters are grouped into facets by semantic type, and will appear in this panel. Note that the Filters panel can be resized or (un)hidden using screen widgets.

Initiating a Search

All searches begin by entering either the name of an astronomical object, or the coordinates of a sky position in the search entry box (on the left in Fig. 2). Enter a positive value in the radius entry box, and select the units for the radius from the pull-down menu. The search can be initiated by clicking the Search button or by pressing the Return key on your keyboard while the cursor is in the search entry box.


Fig. 2—Search panel include the Search Entry and Radius boxes, Units pull-down menu, and Search button, as well as examples of valid search text.

Names of objects are passed to a name resolver (one of many Virtual Observatory services that support the DDT), which associates known object names with sky coordinates. A wide variety of catalog and common names can be resolved to known objects. Coordinates can be given in a variety of formats; right ascensions must be positive and southern declinations require a leading negative sign. Examples of valid names and coordinate formats are given below.

Object Names
`m101`	Objects from standard catalogs such as Messier and NGC will be resolved
`Antennae`	Common names often work
`Hubble Deep Field South`	Famous surveys sometimes work
`T Tau`	Variable star names often work
`BD+19 706`	Star catalogs with coordinate symbols
`png 000.8-07.6`	Other catalogs with coordinate and decimal symbols
`2MASS J04215943+1932063`	All-sky catalogs with coordinate symbols
`TYC 1272-470-1`	All-sky satellite catalogs with restricted symbols
Coordinates
`14 03 12.6 54 20 56.7`	Sexagesimal coordinates delimited with spaces
`14:03.210 54:20.945`	Sexagesimal coordinates delimited with colons; decimal minutes/arcminutes
`14h03m12.6s +54d20m56.7s`	Sexagesimal coordinates with explicit hms/dms
`180.468 -18.866`	Coordinates in decimal degrees

The time required to complete a search will vary from a few seconds to several minutes; searches taking 20 to 30 minutes may be experienced under conditions of very heavy server load, or for large search areas. Partial results should load within a few seconds. Until the search completes a Refresh Table button will appear in the search results bar: click it to update the table with all available rows. A Cancel button will also appear, allowing an immediate termination of the search. While the search is in progress, the text "Search continuing..." will be displayed. Multiple searches can be conduced in parallel by initiating a new search prior to the completion of an earlier search.

Further rules and caveats for valid searches may be found in Tips & Notes.

Exploring Search Results

A successful search, such as that shown for M57 below, populates the Search Results panel with a new table of resources and a corresponding Filters panel applicable to these resources. The results of subsequent searches will be stored in new tables, and can be accessed by clicking on the tabs at the top of the Search Results panel. To eliminate a table (and discard the results for that search), click the "x" icon on the tab. Concurrent searches are possible; if a new search is initiated prior to the last one completing, a new table will be created while the previous search continues. Just below the tabs is a status bar (see caption) with the following items from left to right:

the number of rows retrieved (and update information for searches in progress)
[information on search progress]
[Refresh Table button for searches in progress]
[Cancel button for searches in progress]
Export Table As... button which can write the table of results to your local storage
the object name and coordinates from the name resolver
the search radius

Fig. 3—Appearance of the DDT after a search for m57 within radius = 1 arcmin, showing the filters (left panel) that can be applied to the Search Results (right panel). The results of a prior search may be viewed by clicking the tab (labelled M101 r=1m in this case) at the top of the Search Results panel. At the top of the results table is a Status Bar (red label), which provides details of the search and its progress.

The resources are listed in the table, one per row. Each resource may take the form of a table (such as a catalog), or a collection of images. (Other kinds of resources, such as collections of spectra and SEDs, are planned.) The table gives by default a short summary of information about each resource, including a count of associated images.

Note: Multiple entries in the results table may have identical values in the "Short Name" and "Title" columns. These rows are not duplicates, but are likely multiple types of resources that originate from the same source, such as multiple tables in a journal article, or on-line data that consists of a catalog and an accompanying collection of images. Selecting a row with the cursor (see next section) will bring up additional information for that resource, including its type.

Search Details Pop-Up

Clicking any row in the Search Results table pops up a panel with summary information about the resource, including its type; clicking the double arrows at the bottom of this panel (labelled "Expand for Details") exposes all of the attributes for the resource.


Fig. 4—Summary of the HST resources for m57 within radius = 1 arcmin, showing the summary description of the resource (left). Clicking the double-arrow at the lower-right of the pop-up (see red ellipse at lower right) brings up all available metadata, as shown at right. Clicking the Load button (see red ellipse at upper-left) will create a new tab with the contents of this resource.

Loading Resources to a Table

Clicking the Load button at the upper-left of the pop-up (see upper red ellipse in Fig. 4) will display the full resource contents in a new tab. If the resource is a catalog, it will be displayed in a new table; if the resource is a list of images, attributes of those images will be displayed as columns in the new table as shown in Fig. 5. Note that the number of displayed attributes is sometimes sizable. It is possible to select which attributes are displayed by mousing over any of the column names, clicking the down-arrow icon, mousing over "Columns" in the pull-down menu, and clicking the check-boxes next to the columns of interest, as shown in Fig. 5.

Fig. 5—Attributes of the collection of HST images that match the original search for m57. Note the pull-down menu that is accessible by mousing over any column in the table. This menu permits selecting which image attributes are displayed in the table (though all columns are preserved internally).

Refining Results with Filters

Many searches, particularly on popular targets or of a sufficiently large area of sky, generate sometimes hundreds or even thousands of rows. The Filters panel allows the user to restrict the list of services to those of most interest. A filter can be applied by clicking the check-box next to the filter type. In Figure 6 (left), only those resources matching Optical or UV data would be displayed in the Search Results panel, and that the count of all other resources (e.g., 15 of 44 for Infrared) appear only if they also match Optical and UV.

Filter Facets

The list of potential filters is quite large, and includes as many attributes of the matched data collections as the data providers offer. The filters in the panel are grouped into semantically related facets, the first two of which are always Categories and Waveband. You can view the complete list of facets by clicking the Edit Filters button at the top of the panel; select the desired facets by clicking the check-boxes in the pop-up window (middle) and clicking the Apply button. Note that not all facets are displayed by default.


Fig. 6— Filters panel (left) with filters Optical and UV checked in the Waveband facet. The filters that are visible in the panel may be changed by clicking the Edit Filters button at the top and checking the filters of interest in the pop-up window (middle). Regular expressions may also be used as filters by entering a regular expression in the dialog box near the top of the panel. In this example (right), all results matching HST will be displayed.

Filter Expressions

Finally, regular expressions are a way for advanced users to create custom filters to match resources to their needs. Regular expressions need not be complicated to be useful. In Fig. 6 (right), entering HST in the dialog box near the top of the Filters panel (followed by hitting the "Return" key) will display all resources from Hubble Space Telescope. Note that regular expressions are applied to every field in the table, whether visible or not, to find a match.

Retrieving Results

A core capability of the Data Discovery Tool is to enable users to download resources, or to direct them to other desktop applications for analysis. As used here, resources is a rather generic term used to refer to individual data files (images, tables, and the like), or collections of them, or to services that provide data upon request. Any of these resources may be of use scientifically, and the DDT has simple mechanisms for retrieving them.

Images

Continuing with the example shown in Fig. 5 (a CADC/HST collection of images that match within 1 arcmin the object M57), clicking on a row in the collection of images will pop up a menu for retrieving the FITS image associated with that row. Clicking the Download File button will trigger a browser-specific response for downloading the file. In this example (Firefox), the browser is configured to ask the user what to do with the file.

Fig. 7—Downloading a FITS image of m57 from the CADC/HST Image Search service. Clicking one of the rows pops up an image summary panel; clicking the Download File button (see the red ellipse at the upper left of the panel) brings up a browser-specific menu for dealing with the file.

Note that after clicking the Download File button, your browser (and not the DDT) handles the file. Also be aware that large images may take awhile to download (perhaps tens of seconds, depending on the file size and your internet connectivity). Download progress can only be monitored using browser tools. Finally, note that downloading is disabled for data products that are embargoed by the provider. It may not be obvious when this happens, except that no file will be downloaded to your computer.

Tables

Downloading catalogs is somewhat simpler than downloading images, in that any table displayed in the results panel may be saved with the following steps:

click the Export Table As... button
select the output format and other parameters from the pop-up panel
click the Export button

This procedure applies to search results as well. The operation may be aborted by clicking the Cancel button or dismissing the pop-up panel by clicking the "x" icon. Figure 8 illustrates these steps for sources extracted from the NOMAD catalog that lie within 1 arcmin of M57. This search continues the example from, Fig. 3: the NOMAD resource (row 18 of the original search) was loaded into a new tab, labelled "M57 r=1m: NOMAD".

Fig. 8—Downloading a portion of the NOMAD catalog of astrometric data for sources within one arcmin of m57. After clicking the Export Table As... button, select the output format and other parameters in the pop-up panel, then click the Export button to save the file.

Broadcasting Data via SAMP

Many popular applications, including TOPCAT and DS9, have the ability to broadcast in-memory data to another desktop application that is similarly enabled. The DDT can also broadcast a table, via the Simple Application Messaging Protocol (SAMP). The procedure is exactly the same as illustrated in Fig. 8 for downloading a table, except that instead of clicking Export as the last step, click the Broadcast button. Note that at least one other SAMP-enabled application, such as TOPCAT or Aladin must already be running in order for data to be transferred anywhere. When a table is broadcast (in this case, from the DDT to TOPCAT) for the first time during a session a security notification may appear, similar to that illustrated in Fig. 9.

Fig. 9—Broadcasting a data table to TOPCAT for the first time during a session may result in a security notification. Clicking Yes will complete the operation.

Finally, note that the DDT does not currently support receiving broadcasts of data from other applications.

Tips & Notes

When formulating a search, note the following:

Leading zeros are ignored in the name. For example, M5 returns results for object Messier 005.
Object names are not case-sensitive, and spaces between the characters (e.g. M51 and M 51) are ignored unless the space indicates a real character in the name.
If an object name is incomplete the name resolvers from NED and SIMBAD return the closest match. This can lead to surprising results however.
All coordinates are interpreted as J2000.
Maximum search radius is 2°.
Queries are currently limited to a single object or position. However, multiple queries may be invoked sequentially, even if one or more queries are still executing.

While executing a search, note the following:

The time required to complete a search will vary from a few seconds to several minutes; searches taking 20 to 30 minutes may be experienced under conditions of very heavy server load, or for large search radii. The search duration is also limited by the response time of remote data provider services, which in some cases may be considerable.
Multiple searches may be conducted at once, in parallel. Simply enter a new object or coordinates in the search box, update the search radius if necessary, and click the Search button. The prior search, if it is still executing, will continue unaffected.
An active search may be terminated prior to completion by clicking the Cancel button. Any rows in the Search Results panel may still be explored.
Tables of search results are not saved between sessions; once the application has been abandoned, returning to it will not bring up previously searched objects.

When downloading an image, note the following:

After clicking the Download File button your browser (and not the DDT) handles the file.
Large images may take awhile to download. Download progress can only be monitored using browser tools.
Downloading is disabled for data products that are embargoed by the provider. It may not be obvious when this happens, except that no file will be downloaded to your computer.

When downloading a table, note the following:

The Export Table As... operation refers to the currently visible table, and not to a selected row within the table.

When broadcasting a table, note the following:

At least one other SAMP-enabled application, such as TOPCAT or Aladin must already be running in order for data to be sent anywhere.
The Data Discovery Tool cannot currently receive data sent from other applications.

Questions or problems? Please contact the VAO HelpDesk.

Last modified: 2012-Jan-24

US Virtual Astronomical Observatory User Documentation