Conducting a Property Search
The catalog may be searched in one of two ways in the Query tab of CSCview, using either a "standard query" designed by a CXC scientist, or by building a custom query. In this thread, we consider the example of a custom query which searches for all sources in the catalog which have a hard-to-soft hardness ratio of 0.0 or less, and which are not extended, piled-up, or confused with other sources.
In order to search the catalog for sources satisfying specific source property conditions, e.g., all sources associated with ObsId 617, or all sources with a broad-band energy flux above a certain threshold, the desired source property condition(s) should be defined in the Search Criteria window in the Query tab of CSCview (which has an ADQL interface accessible via the "View->Query->Show Language" menu item).
Last Update: 24 Nov 2010 - updated for CSCview version 1.1.1
- Conducting a Property Search in the Query Tab
- Conducting a Property Search in the ADQL 2.0 Interface
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 locate all master sources in the catalog with a hard-to-soft hardness ratio of zero or less, we select 'hard_hs' from the Spectral Hardness Ratios->ACIS Hard-Soft Energy Bands section of the Master Sources list of properties and drag it to the Search Criteria window. Next, we set 'hard_hs <= 0.0'. In this example, we choose to work with data contained in the Master Sources Table since it records the best estimates of the source properties derived from the individual observations of a source.
Since we are interested in finding sources that are not confused, piled-up, or extended, we select 'conf_flag', 'pileup_flag', and 'extent_flag' from the Source Flags section of the Master Sources list and set them all to 'F' (or '0', for false) in the Search Criteria Window.
The search criteria have now been set, with all connected by 'AND' search logic.
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.
Now that the search conditions for the catalog query have been set, we specify in the Result Set window which master source properties we would like returned for all sources found in the search. In this example, we would like to retrieve the source name and equatorial position, as well as the actual value of the hard-to-soft hardness ratio. To do this, we select 'name', 'ra', 'dec', and 'hard_hs' from the Master Source Properties list and drag them to the Result Set window. We also add the 'dataset_id' source property from the Data Products category, in order to be able to access data products associated with sources returned by the search. To set the ordering of the columns of the query results table, we highlight 'hard_hs' in the Result Set window and drag it upwards two rows (or select the "^" button to do so).
Finally, we change the 'Select' option from the default '1000' to 'all' to retrieve data for all sources found in the search.
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 five source properties in the Result Set window of the Query tab, the results table contains these five columns and as many rows as sources found in the database search. (Note that the 'dataset_id' column is automatically entered into the result set of CSCview startup and standard queries, so that data products associated with sources returned by the search may be accessed. In this example, we had to add it ourselves since we cleared the CSCview startup query initially).
The results may 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.
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 hard-band PSF image of the source in the ninth row of the results table is shown below.
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 m.name, m.hard_hs, m.ra, m.dec, d.dataset_id FROM dataset d, master_source m WHERE ((m.hard_hs <= 0.0 AND (m.conf_flag = 0) AND (m.extent_flag = 0) AND (m.pileup_flag = 0)) AND m.msid=d.msid
Note that the 'd.dataset_id' column is automatically entered into the result set of a default startup query or a standard query (in this example, however, we had to add it ourselves since we cleared the CSCview startup query initially). This number uniquely identifies the set of data products associated with each source in the catalog; we may remove it from the query expression if we do not wish to retrieve data products for the sources found in the search.
|07 Oct 2008||original version|
|26 Feb 2009||updated for CSC Release 1|
|21 May 2009||updated for CSCview version 1.0.2|
|11 Aug 2010||updated for CSCview version 1.1|
|24 Nov 2010||updated for CSCview version 1.1.1|