Using Source Property Associations

Using the 'match_type' source property in the Query tab

The Master Sources/Source Observations Associations group contains the 'match_type' column, which labels a source observation found in a query search as either ambiguously ('a') or uniquely ('u') matched to a master source. If a source observation is ambiguously matched to a master source, it lies within the same area of the sky as the master source, but it can be matched to more than one distinct source in the area. Such a source observation is characterized as confused, therefore it is ambiguously matched to at least two master sources, and its properties do not contribute to any master source properties recorded in the Master Sources Table. A source observation that is uniquely matched to a master source is one that clearly corresponds to the same source in the same region of sky in multiple, overlapping observations; its properties contribute to the master source properties recorded in the Master Sources Table. (Note, however, that if a uniquely matched source observation is piled-up, its properties will not contribute to the corresponding master source properties UNLESS it is an ACIS observation and all other ACIS observations of that source are also piled-up.)

Establish search criteria

To begin our example 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 observations in the catalog which targeted supernovae, we select 'targname' in the Observation-Specific Information->Observation Target and Pointing->Observation Target category of the Source Observations list and drag it to the Search Criteria window. We set 'o.targname LIKE SN%' as the source property search condition for the query; the special character '%' will locate source names starting with 'SN' (for 'supernova'), followed by any set of characters.

A search on observation target name in the Query tab of CSCview

---

Select desired results

Once the search condition for the catalog query has been established, we specify in the Result Set window the desired source properties to be returned. The source observation properties in which we are interested are the IDs and full target names of all observations with a target name beginning with 'SN'; the IDs of the source regions located within each of those observations; and the equatorial coordinates and broad-band flux significance of the source observation regions. We would also like to know the catalog names, equatorial coordinates, and flux significance of any master sources linked to each source observation region located in the search. Finally, to know how each source observation region is associated with corresponding master sources, we utilize the Master Sources/Source Observations Associations -> match_type catalog column. To complete the query, the desired source properties are selected from the Source Properties window and dragged to the Result Set window: dataset_id from the Data Products category, obsid and targname from the Observation-Specific Information category; region_id, ra_b, dec_b, and flux_significance_b from the Detected Source Properties category; name, ra, dec, and significance from the Master Source Position and Source Flux Significance categories; and the Master Sources/Source Observations Associations -> match_type column.

Finally, we change the 'Select' option from the default 'top 1000' to 'all' to retrieve data for all sources found in the search; we sort the query results by 'o.obsid' in ascending order; and set the column ordering of the query results table to be returned as follows: from top to bottom (left to right in search results table), name, ra, dec, o.obsid, o.region_id, a.match_type, o.ra_b, o.dec_b, o.flux_significance_b, significance, o.targname, and d.dataset_id.

Complete query in the Query tab of CSCview

---

Submit query

The database query is now complete; we may submit the query by selecting the 'Search' button. When the catalog search finishes, the query results interface appears with a table of results displayed in the Results tab. Since we entered twelve source properties in the Result Set window of the Query tab, the query results table contains twelve columns; and since we set 'Select' to 'all' in the Query tab, the full set of matching results is returned in the table (3005 rows of data).

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.

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. We may also preview source region and full-field images of sources in selected rows of the results table using the Source Preview, accessible via the clickable "View" buttons in the table rows.

Understanding query results: Master Source vs. Source Observation Properties

The full set of query results shows that tens of Chandra observations (ObsIDs) over the last eight years targeted supernovae, and many source regions within each of those observations (identified by 'o.region_id') are available for study. We see clearly the differences in equatorial coordinates and flux significance between the source observation and master source properties, with the master source properties representing the best estimates of the source properties derived from a set of corresponding source observations, and in this case, across all science energy bands. For this reason, it is apparent why the properties of source observation regions which are ambiguously matched (match_type 'a') to multiple master source regions are not used in the determination of master source properties (e.g., flux estimates of a confused source would likely be significantly larger than the true flux of 'correct' master source to which it is linked). For more information on the distinction between master source and source observation entries in the CSC, see the Catalog Organization page.

Pictorial demonstration of the manifestation of confused sources in the CSC

To place confused catalog sources in a better context - such as source region 2 of ObsId 735, which we see is a confused source on account of the fact that it is ambiguously linked to two different master source names - we can search the catalog for all other source observations linked to one of those master sources, CXO J095549.2+685834.

We return to the Query tab, clear the Search Criteria window, and enter the desired master source name, 'name = CXO J095549.2+685834'; we keep the Result Set source properties as specified in the previous query.

After submitting the new query, the Results tab opens with a table containing source properties of all source observation regions linked to master source CXO J095549.2+685834.

Query results interface of CSCview (Results tab)

In this example, source region 2 of ObsID 735 is one of eighteen source observation regions from other ObsIDs which are ambiguously linked to the master source, on account of confusion and/or pile-up. The only source region whose properties contribute to the master source properties of CXO J095549.2+685834 is source region 33 of ObsID 5949.

Using the 'match_type' source property in the ADQL 2.0 interface

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). The queries we built in the main form would be translated into ADQL as follows:

Query 1

SELECT m.name, m.ra, m.dec, o.obsid, o.region_id, a.match_type, o.ra_b, o.dec_b, o.flux_significance_b, m.significance, o.targname, d.dataset_id FROM dataset d , master_source m , obi_source o , master_obi_assoc a WHERE ((o.targname LIKE "SN%")) AND o.posid=a.posid AND m.msid=a.msid and o.posid=d.posid ORDER BY o.obsid ASC

Complete query in the ADQL interface of CSCview

Query 2

SELECT m.name, m.ra, m.dec, o.obsid, o.region_id, a.match_type, o.ra_b, o.dec_b, o.flux_significance_b, m.significance, o.targname, d.dataset_id FROM dataset d , master_source m , obi_source o , master_obi_assoc a WHERE ((m.name = "CXO J095549.2+685834")) AND o.posid=a.posid AND m.msid=a.msid and o.posid=d.posid ORDER BY o.obsid ASC

Complete query in the ADQL interface of CSCview