Conducting a Cone Search

Establish search criteria

To begin our query, we first clear any example entries which may be present in the interactive windows of the Query tab by selecting the "File→New→Empty Form" menu option - or by highlighting these items and selecting the "-" button next to the appropriate window. (You may choose to have the query form appear empty upon startup, or populated with an example query with the "Startup Query" option in "Edit→Preferences"; the latter is the default startup option.) To specify that we wish to locate all sources in the catalog within 100 arcminutes of a location in the Rho Ophiuchus core, we enter into the "Cone search" window of the Query tab the center position and radius of a circular area on the sky we wish to search, using the "By Coordinates" option. We prefer equatorial coordinates to Galactic, so we select "Equatorial" from the list of options and enter the center location on the sky in sexagesimal notation, 'ra: 16:27:10.2' and 'dec: -24:19:13'. Finally, we set the radius of the cone search to '100' arcminutes. The search criteria for this query have now been set. (The "By Name" option of the Cone Search uses thhe "Resolver" feature which internally locates the coordinates of a source associated with a user-input target name.)

Cone search in the Query tab of CSCview

The metadata display at the bottom of the CSCview Query tab lists the name, data type, units, and description of each source property selected in the Source Properties window. For extended, high-level descriptions of each source property included in the catalog, see the "Catalog Columns" page of the CSC website.

Select desired results

Now that the search conditions for the catalog query have been established, we specify in the Result Set window which master source and/or source observation properties we would like returned for all sources found in the search. (Note that the distance of each source from the specified set of coordinates is automatically added to the result set under the name "separation", in units of arcseconds.) In this example, we would like to know the IDs of the full-field observations in which each source is found, the CXC names of any master source entries linked to those sources, as well as the best estimates of the derived ACIS broad band and hard band aperture source energy fluxes for the sources. To complete the query, we drag the following source properties from the Source Properties window to the Result Set window: the master source 'name', and 'photflux_aper_b' and 'photflux_aper_h' from the "Aperture Photometry→Source Region Aperture Fluxes→Photon Fluxes" category of the Master Source list; and 'obsid' and 'obi' from the "Observation-Specific Information" category of the Source Observations list.

Finally, we decide to sort the search results by source observation ObsId ('o.obsid'), and change the 'Select' option from the default 'top 1000' to 'top 10' to retrieve data for the first ten sources found in the search.

Complete query in the Query tab of CSCview

Submit query

The catalog query is now complete; we may submit the query by selecting the "Search" button in the toolbar. When the search finishes, the query results interface appears with a table of results displayed in the Results tab. Since we entered seven source properties into the Result Set window of the Query tab, and set 'Select' to '10', the query results table contains these seven columns and ten rows.

Query results interface of CSCview (Results tab)

The results may now be saved to a text file by selecting the "Save" toolbar button while the Results tab is open. (Note that the results of a catalog search can be saved to a file without ever having to leave the Query tab by clicking the box "Save Results to File" in the upper-right corner of the query form). To convert a Tab Separated Values (TSV) format save file output by CSCview to a CIAO-compatible text file, refer to the thread Using a CSC Save File in CIAO.

Source Preview Unavailable

This section will be updated shortly. The Source Preview is unavailable in the current publicly released version of CSCView.

At this point, we may also browse and download data products associated with sources found in the search, as described in the thread Retrieving Data Products. However, before proceeding to the Products tab to download selected data products, we may preview source region and full-field images of sources in selected rows of the results table using the Source Preview in the Results tab, accessible via the clickable "View" buttons in the table rows. The source region images available include a "tricolor" soft-medium-broad events image, a single-color events image in any of the selected CSC energy bands (broad, hard, medium, soft, ultrasoft, wide), and a PSF image in any CSC energy band. The full-field broad-band events image is available at different blocking factors (1, 2, and 4 for ACIS). The full-field events image of the source in the fourth row of the results table is shown below, at a blocking factor of 4.

Preview of the CSC broad-band full-field image of a selected source in the results table (Results tab)

The image displayed in Source Preview may be saved to a JPG file by selecting File→Save within the Source Preview window. Note that Source Preview is only available when the 'dataset_id' catalog column is included in the search results, as this property is used to uniquely identify the set of data products associated with each source.

ADQL 2.0 query

CSCview is form-based, but converts a query to ADQL 2.0 for execution. Users may write ADQL queries directly in CSCview by selecting the menu option "View→Query→Show Language" while the Query tab is open, or non-interactively on the Unix command line (see the CSC Command-Line Interface page for examples using cURL and Wget).

A query constructed in the main form of the Query tab is automatically translated upon reaching the ADQL view (however a query originally defined in the ADQL view cannot be imported into the main form). Here is the ADQL 2.0 version of the query we defined in the main form of the Query tab:

SELECT top 10 dbo.separation(m.ra,m.dec,246.79250000000002,-24.32027777777778) as separation,m.name,m.photflux_aper_b,m.photflux_aper_h,o.obsid,o.obi FROM master_source m , master_stack_assoc a , observation_source o , stack_observation_assoc b , stack_source s WHERE ((( ( m.dec BETWEEN -25.986944444444447 AND -22.65361111111111 ) AND ( m.ra BETWEEN 244.96352572828027 AND 248.62147427171976 ) ) AND dbo.cone_distance(m.ra,m.dec,246.79250000000002,-24.32027777777778)<=100.0)) AND (m.name = a.name) AND (s.detect_stack_id = a.detect_stack_id and s.region_id = a.region_id) AND (s.detect_stack_id = b.detect_stack_id and s.region_id = b.region_id) AND (o.obsid = b.obsid and o.obi = b.obi and o.region_id = b.region_id)ORDER BY obsid ASC:

Complete query in the ADQL interface of CSCview

VO cone search

A VO cone search service is also available for conducting a search on source position in the CSC. It follows the IVOA cone search recommendations, with a fixed-call syntax which does not get combined with CSC cone searches in ADQL.

In the VO cone cearch, one searches on RA, DEC and SR (search radius) in decimal degrees, and receives one of the three available result sets, based on the value of the parameter VERB (verbosity):

• verbosity = 1 reports the source name, RA and DEC values from the Master Sources Table for each matching source resulting from the cone search
• verbosity = 2 reports the master source summary results and Space Time Coordinate (STC) metadata
• verbosity = 3 reports all the columns in the Master Sources Table

The VO cone search may be executed on the Unix command line using the query syntax of a command-line tool such as cURL or Wget. A VO cone search on the source position used in this thread, using a search radius of 1.66 decimal degrees and verbosity level 2, would appear as follows, where we perform the query using Wget:

unix% wget -O out.vot 'http://cda.cfa.harvard.edu/cscvo/coneSearch?RA=246.7925&DEC=-24.32027&SR=1.66&VERB=2' 

The output file out.vot contains the full result set of the Wget query.