Search http://cxc.harvard.edu/csc2/ Contact the CXC HelpDesk
Last modified: 16 January 2024

URL: https://cxc.cfa.harvard.edu/csc/gui/intro.html
/ csc / gui / intro.html

CSCview and CSC 2.0 Help

Software Requirements | CSCview Threads | CSC Homepage | Command-line Interface
Get CSCView

CSCview is a GUI application which provides direct access to the contents of the catalog via user-specified queries. Search criteria and desired results are specified using the source properties contained in the catalog, which are split into three categories: Master Source, Stack ([New] in CSC 2.0), and Source Observation properties. CSCview provides access to the current database of the catalog—which includes the most recently processed data sets which have not yet been included in the next release—as well as catalog releases, which are carefully reviewed, static versions of the CSC.

As of October 24 2019, the default database for CSCview is Release 2.0.

[CSCview screenshot]

Starting CSCview

The CSCview application is written in Java and so may require installation of additional software or changes to the settings of the operating system. Please refer to the Software Requirements page for further details.

Once CSCview has been downloaded, it can be started with (assuming the jar version was downloaded; Mac OS users can use the DMG version which provides an application that starts CSCview): 

unix% java -jar cscview.jar

unless you use Java 9 only, in which case you will have to say: 

unix% java--add-modules java.se.ee  -jar cscview.jar

The CSCview GUI

The face of CSCview is reminiscent of that of a web browser, with standardized menus like File, Edit, and Help, as well as clickable icons representative of the most commonly used menu options, such as New, Open, and Save. However, the tabbed pages are not independent of one another as they are in a web browser; the Results tab remains empty until a query is submitted in the Query tab, and the Products tab is not populated with information until data products are selected on the Results page. Furthermore, the menus are adapted to the different tabs; whereas some menu options apply to all the tabs, others are active in only some of the tabs. For ease of use, first-time users of CSCview are encouraged to begin a search by reading the "Getting Started" help guide which pops up when CSCview is opened, as well as browsing the pull-down menus at the top of the GUI to become familiar with all of the available options.

[TIP]
Tip

Questions about CSCview should be submitted to the CXC Helpdesk using the subject "Chandra Source Catalog".

Catalog View

The CSCview Catalog tab allows you to choose which version of the catalog to access: the current database view ("Current Database") or a release view ("Release"). A catalog release view is a carefully reviewed, static version of the CSC. It is appropriate for the user who requires a detailed characterization of the statistical properties of the catalog, such as limiting sensitivity, completeness, false source rates, astrometric and photometric accuracy, and variability information. The database view provides direct access to the active CSC database as it exists at the time of query submission. This view includes the most recently processed data sets which have not yet been included in a catalog release. See the CSC web page Catalog Release Views and Database Access Views for more information.

[IMPORTANT]
Important

CSCview opens on the Query tab, with the most recent release view selected by default in the Catalog tab. This defaults to Release 2.0.

To query the catalog using a view other than the most recent release view, open the Catalog tab, select the desired catalog view, and then the Search icon to go back to the Query tab.

Query Interface

You can query the catalog database in one of two ways in the Query tab, using either a "standard query" designed by a CXC scientist, or by building your own custom query.

Standard Query

  • Select one of the example queries listed in the Standard Results box and drag it towards the right side of the Query tab; this will cause the appropriate search fields to automatically populate with entries specific to the example.

Custom Query

  • Make selections from among the list of CSC source properties and drag them into the Search Criteria, Result Set, and Sort Order fields (and/or define a cone search around a given sky position, and/or specify a crossmatch query).
  • Write query expressions in the Astronomical Data Query Language (version 2.0) in the ADQL view of the Query tab, which is accessible via the menu option View → Query→Show Language.
  • Build upon a standard query by selecting one and dragging it into the query form to populate the interactive windows, and then adding to or modifying the Search Criteria, Result Set, and/or Cone Search fields.

The Getting Started guide which pops up alongside CSCview provides a brief overview of the features of each CSCview tab, as well as a set of instructions for loading standard queries and building custom queries. Selecting the Edit →Preferences→Startup Help→None menu option will prevent this guide from automatically opening when CSCview is launched.

[screenshot of Getting Started window]

Query Tab

To quickly start a query in the Query tab of CSCview, simply select one of the "standard queries" provided and drag it to the Search Criteria area, which will populate the interactive areas with the example values. Otherwise, you can build a custom query by selecting and dragging the provided "source properties" into the Search Criteria window to define the search conditions for a catalog query, and into the Result Set window to specify the desired quantities to be returned by the search. The "+" button in the query fields may also be used for adding source properties. Multiple source properties may be selected simultaneously by pressing and holding either the keyboard Control, Shift, or Command key while selecting the desired source properties with a mouse cursor.

The sort order of the table of search results to be returned may be specified by dragging one of the source properties listed in the Result Set window to the Sort Order window (as well as by clicking the header of the sort column in the table of search results returned in the Results tab).

A cone search around a single sky position or crossmatch query around multiple sky positions may be entered as the sole search criterion in the Query tab, or used in conjunction with other constraints entered into the Search Criteria window.

The query can be saved to a text file by selecting the Save icon, and re-opened in a future session of CSCview with the Open icon.

The "+", "-", and up/down arrow buttons next to each interactive field in the Query tab allow you to add selections from other fields to the current field, remove selections from the current field, or move up/down one or more selected source properties contained within the field.

Standard Queries

Many example queries are available as search templates in the Standard Results window of the Query tab. To populate the query form with one of these queries, simply select one from the list and drag and drop the selection anywhere in the query form to the right. These queries can be combined, or you can clear the query form between each selection with File →New→Empty Form".

The standard queries consist of Master Source Basic Summary, Master Source Summary, Master Source Photometry, Master Source Variability, Stack Source Summary, Stack Source Photometry, Source Observation Summary, Source Observation Photometry, and Source Observation Variability. The Master queries return properties from only the Master Sources Table, whereas the Stack and Observation queries include a mix of properties from the Master Sources Table and either the Stack Table or the Per-Observation Detections Table respectively.

The Standard Search Criteria section of the Standard Results window consists of four options: Search by Stack Identification, Search by Observation Identification, Search for Variable Sources, and Search for Isolated Sources. For the first two obtions, the search property—s.detect_stack_id and o.obsid respectively—is added to the Search Criteria window, and the value (to the right of the = sign) is used to enter the search value. The variablility query is more complex, since it involves restrictions on many properties related to source variability. The query selecting isolated sources applies criteria based on properties from different tables.

Source Properties

The source properties listed on the Query tab of CSCview are categorized into eight groups (this has been significantly expanded from the 1.1 release): Master Sources, Stacked Observation Dectections, Per-Observation Detections, Master Source/Stack Source Associations, Stack Source/Observation Source Associations, Detect Stack, Valid Stack, and Likely Stack. These represent the "columns" of the catalog tables, i.e., source quantities or parameters that are officially part of the catalog. A brief description of a source property is displayed in the metadata display at the bottom of the Query tab when selected, including data type and units.

The master source properties are recorded in the Master Sources Table, and represent the best estimates of the properties of a source, based on the data extracted from the set of observations in which the source has been detected.

The per-observation detections properties are those which result from an individual observation (Obi) of a source, and are recorded in the Per-Observation Detections Table.

The Master Source/Stack Source Associations table contains the name, detect_stack_id, region_id and match_type columns. This table allows to connect master sources to their associated stack-level detections. The name column contain the unique identifier associated to a master source; the detect_stack_id column contains the identifier of the stacked observations where the stack-level detection contributing to the name master source are located, and the region_id column represents the integer specifying the individual region of the stacked observation stack_detect_id associated to the master source name. The match_type column labels a source observation found in a query search as either ambiguously (a) or uniquely (u) matched to a master source.

The Stack Source/Observation Source Associations table contains the detect_stack_id, obsid, obi, cycle and region_id column. This table allows to connect stack-level detections to the associated single-observations detections. The detect_stack_id column contains the identifier of the stacked observation where the stack-level detection is located; the obsid and obi columns contain the observation identifiers and the observation interval number, respectively, and they univocally identify the single observation where the stacked observation detection is located. The column cycle specifies the ACIS readout cycle for the single observation detection, and the column region_id is an integer identifier for the detection region of the stacked observations and single observations detections.

The Detect Stack table contains the detect_stack_id, obsid, obi and cycle columns. The detect_stack_id column contains the identifier of the stacked observation where the stack-level detection is located; the obsid and obi columns contain the observation identifiers and the observation interval number, respectively, that univocally identify the single observation where the stacked observation detection is located. The column cycle specifies the ACIS readout cycle for the single observation detection. The Valid Stack and Likely Stack tables contain the same columns of the Detect Stack tables with the addition of the region_id column, that identifies the detection region of the stacked observations and single observations detections.

The Search Criteria window of CSCview accepts properties from all the tables listed in the Source Properties window. In other words, only sources satisfying the conditions set forth in the Search Criteria window will be included in the query results. (If the Search Criteria window is left empty, it is assumed that the source properties specified in the Result Set window of the Query tab should be returned for all sources in the catalog.) The source properties can be dragged and dropped into the Search Criteria window with a mouse cursor, or by selecting the desired properties and then clicking the "+" button by the Search Criteria window.

Source observation properties from the Stack Observation Detections, Per-Observation Detections, Master Source/Stack Source Associations, and Stack Source/Observation Source Associations tables are prefixed with 's.', 'o.', 'a.', and 'b.' respectively, to be distinguished from properties with the same names in other tables. Additional properties from the Detect Stack, Valid Stack and Likely Stack tables are prefixed with 'd.', 'v.', and 'l.'. Once the source properties have been added, you have the option to set each property =, !=, >, <, >=, or <= a specified quantity. Additionally, the Boolean clauses IN, BETWEEN, LIKE, NULL, NOT NULL, and TRUE/FALSE may be used to set the search criteria for the database query. The Boolean clause 'IN' accepts a comma-delimited list, such as 'acis_num IN 2,3' (m.acis_num IN (2,3) in the ADQL interface). The Boolean clause LIKE accepts a case-sensitive string, with the following special characters:

In the ADQL interface, the search term has to be quoted, so the last example would be written: o.targname LIKE "[^agkm]%".

A given source property may be entered into the Search Criteria window multiple times, e.g., to define a source property range such as 'src_cnts_aper > 100' and 'src_cnts_aper <= 50'. The 'match_type' column is special, in that it can only be entered once as it is used to specify how to combined stacked observations detections and master source properties Each of the source property conditions listed in the Search Criteria window may be related by an appropriate AND/OR logic statement to specify if the sources found in the database search are to satisfy all or a subset of the source conditions, with a corresponding set of parentheses for delimitation; the pull-down menus located on either side of each source property condition in the Search Criteria window may be utilized for this purpose. All searches are case-sensitive.

Result Set

To specify the desired quantities to be returned for each source that satisfies the conditions set forth in the Search Criteria window (and/or in a cone search), the appropriate source properties should be entered into the Result Set window. The source properties contained in the Result Set window correspond to the columns of the catalog table(s), and will appear as the columns in the query results table to be returned. If the Result Set window is left empty, an error will be returned: "You need properties in the Result Set to run this query. Try adding a Standard Query." The source properties can be dragged and dropped into the Result Set window with a mouse cursor, or by selecting the desired properties and clicking the '+' button by the Result Set window. A source property may not be entered multiple times into the Result Set window.

The table of search results to be returned may be sorted on any of the source properties entered into the Results Set window (one or multiple), in ascending or descending order; the sort order is specified by dragging one or more of the Result Set source properties into the Sort Order window. If multiple source properties are added to the Sort Order window, the order in which they appear is the order by which the table of search results will be sorted. The column ordering of the table will reflect the order specified in the Result Set window. The default units in the query results table for any ra*/dec* columns selected is sexagesimal notation, hh:mm:ss.s, ±d:mm:ss.s; the output coordinate format may be changed to decimal degrees with the Edit→Preferences→Output Coordinate Format menu option.

The Select option above the Result Set window allows the user to specify as few as 10 rows of results to be displayed at a time in the query results interface, and as many as all, once the query has been submitted. It also features the count item, which will return only one number when the search finishes: the total number of search results found (total_count). Revisiting the Query tab, changing Select: count to Select: all, and re-submitting the query will return this number of rows of data in the Results tab.

The full table of search results may be saved to a text file by selecting Save while the Results tab is open, or by clicking the Save results to file box in the upper-right corner of the Query tab before submitting the query.

The 'rows/distinct rows' option of the Select feature can be used to display or hide duplicate source entries in the query results table to be returned, as certain types of queries can (correctly) return multiple entries for a given source. For example, confused sources in the catalog (match_type='a') are associated with at least two different master source names since they cannot definitively be matched to a single source. As a result, a query including a mix of master source and per-observation detection properties may return the same set of per-observation detection properties for multiple master source names (though the confused source properties do not contribute to the calculation of the corresponding master source properties). 'Select: rows' is the default setting for a blank query, but note that 'Select: distinct rows' is used in all of the master source standard queries provided.

The Cone Search feature beneath the Search Criteria window may be used to conduct a cone search of a specified radius in arcseconds, arcminutes, or degrees around a set of coordinates. Equatorial and Galactic coordinates are accepted in decimal degrees, as well as sexagesimal notation for the Equatorial option (e.g., hh:mm:ss.s, ±d:mm:ss.s). All sources in the CSC located within the specified radius (and satisfying any other search conditions) will be returned; 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.

The Resolver feature of the cone search locates the coordinates of a source internally by conducting a target name search of the SIMBAD and/or NED astronomical databases. If the target name provided is recognized when the query is submitted, the query will complete successfully; if not, a message will be printed to the screen indicating that the name could not be resolved.

Note that a specified cone search will be carried out in conjunction with any search conditions set forth in the Search Criteria window (i.e., the Search Criteria conditions are connected to the cone search conditions by an AND). For example, if a user has entered obsid=617 in the Search Criteria box to locate all per-observation detections associated with "ObsID 617", but has also entered a cone search of an area of the sky which overlaps many ObsIDs, including ObsID 617, the query results returned will consist only of sources matching ObsID 617, not all sources matching all ObsIDs returned by the cone search.

—using command-line tools:

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. 

unix% curl 'http://cda.cfa.harvard.edu/cscvo/coneSearch?RA=83.77333&DEC=-5.68464&SR=.233&VERB=1'

unix% wget -O out.vot 'http://cda.cfa.harvard.edu/cscvo/coneSearch?RA=83.77333&DEC=-5.68464&SR=.233&VERB=1'

In the VO Cone Search, one searches on RA, DEC and SR (search radius) in demical degrees, and receives one of the three available result sets, based on the value of the parameter VERB (verbosity). The CSC Cone Search page provides a full list of columns returned by the three verbosity values, with 1 returning the least information and 3 the most.

Position Search: Crossmatch

The CSCview Crossmatch feature allows you to upload, transmit, or directly enter a table of source positions into the GUI and return the list of all CSC source positions which match the sources in the input list, determined by your search criteria and the crossmatch algorithm used by CSCview. The separation of each CSC source match from the corresponding source in the input list is also returned, in arcseconds, along with a measure of the probability that it is a true match. A probability value of 1.0 means that the CSC source returned for the corresponding source in your input list is an exact match (down to many significant digits in the source position), and a probability of 0.0 means it is very unlikely that it is a true match. You may specify the radius within which to search around each input source position in the crossmatch query, in arcminutes or arcseconds, with the default being 3 arcminutes (which is an appropriate value for off-axis point sources which may actually be extended, but is likely too large for on-axis point sources). You may also provide source position errors to be used in the calculation of the probability value of each match. If you do not provide position errors for your sources, the errors used in the probability calculation are the CSC err_ellipse_r0 source position errors associated with the CSC source matches located within the search radii of your input sources. The best match of all CSC sources returned for a single source in your input list is the CSC source with the highest probability value associated with it.

The User Table parameter of the crossmatch lists three options for entering tables of source positions, described below. The input table in each case must contain at least two columns of data for the RA & Dec., source positions, and optionally, the following additional columns: a column of source position errors in arcseconds; a column of source object identifiers, e.g., strings identifying each source in the list, such as "3c273" or "source 1", "source 2", etc.; a column of search radii in arcseconds for defining the cone search which will be conducted for each source in the input list.

  • User Table
    • Local file

      Use this option to upload source positions from either a TSV or VOTable format file.

    • New Table

      Use this option to enter columns of source positions directly into a window which pops up from the GUI. A header is not required with this option.

    • Received Table

      Use this option to select a table of source positions transmitted from a SAMP-connected remote client, such as a table entry from the Table Browser window of the TOPCAT application. WARNING: CSCview truncates an incoming table at 250000 rows, without issuing a warning.

If the optional columns of data are not provided, i.e., the input table contains only columns of source position RA and Dec., then the default values for the source position errors, source object identifiers, and cone search radius will be used.

  • Radius

    A single entered radius, or a selected column of radii from the user-input table, in arcsecs/arcminutes within which to search around each input source position for a CSC source match; default value is 3 arcminutes.

  • Sigma

    Source position sigma error value(s) to assume for input sources, either a single entered value to apply to all sources in the list, or a selected column of errors from the user-input table. For example, a value of 1.0 means that the crossmatch search will assume that each of the source positions in the input list have associated 1-sigma source position errors.

  • Object ID

    The string to use to identify each source in the user-input list in the returned table of crossmatch search results, either default rowindex or a selected column from the user-input table.

[NOTE]
Note

The Radius parameter sets the radius of the circle around each user-supplied source within which the crossmatch algorithm searches for matching CSC source positions. You should be aware that drastically different values for Radius are appropriate when searching on-axis or off-axis CSC sources because of the large variation in CSC source position uncertainty with off-axis angle. For the on-axis sources you may prefer a Radius of one or a few arcseconds, while far off-axis sources can only be adequately matched with Radius between 2 and 3 arcminutes. The default value is set to 3 arcminutes to ensure that one gets complete matching over the full Chandra field-of-view. However, this value may produce a large number of spurious matches over a large area around the center of the field. You can eliminate many of these spurious matches by adding the c.probability source property to the Search Criteria window of the Query tab and setting it greater than or equal to (>=) a relatively high value, e.g., c.probability>=0.6. When the crossmatch query is submitted, this will ensure that only source matches with probabilities higher than 0.6 will be returned.

The default setting for the Sigma source position error parameter is null, meaning that no user-specified source position errors will be assumed for the sources in the input list, and that the only errors which will be used to calculate the probabilities of the returned matches are the CSC err_ellipse_r0 source position errors associated with the CSC source matches.

The default setting for the Object ID parameter is rowindex, which will be used to label user-input sources in the returned table of crossmatch search results in the event that this optional column of data is not included in the user-input table; sources will be labeled as row 1, row 2, and so on.

ADQL 2.0 command-line interface

—within the GUI:

CSCview allows you to query the catalog by transmitting an Astronomical Data Query Language (ADQL) query expression. ADQL is a database language designed to enable sophisticated queries of an astronomical database from the command line, such as with the SELECT, TOP, FROM, WHERE, ORDER BY statement supported by the ADQL view of the Query tab. This view is accessed by selecting the menu option View→Query→Show Language while the Query tab is open.

ADQL 2.0 (case-sensitive) query expressions can be constructed to establish database search criteria and produce query results equivalent to those which result from the main view of the Query tab (the query in the ADQL view need not match the query defined in the Query tab in a given session of CSCview). If a query has been defined in the main view of the Query tab, upon entering the ADQL view the user will find the ADQL translation of this query (this does not work in reverse—a query expression defined in the ADQL view cannot be imported into the standard form of the Query tab). If a query has not been previously defined, the ADQL view appears with "SELECT top 1000 ' ' FROM master_source m"; you may edit the statement by dragging the provided source properties into the command-line window. To view examples of full ADQL query expressions, simply drag one of the standard queries to the ADQL query window. An ADQL query can be saved to a text file by selecting the Save option from the File pull-down menu.

An ADQL SELECT statement returns a result set of records from one or more tables of astronomical data, located by the FROM clause. The available tables are master_obi_assoc a, master_source m, observation_source o, and dataset d for the CSC. Some of the optional clauses of a SELECT statement include:

  • TOP—specifies the number of rows to retrieve.
  • WHERE—specifies which rows to retrieve, according to the search criteria
  • ORDER BY—specifies an order in which to return the rows

For example, submitting the following query in the ADQL tab will retrieve these results: the master source name, master source significance, master source broad band energy flux, and master source power law model photon index for the first 1000 catalog sources found which have a master source significance greater than 10.0, pile-up fraction smaller than ~10%, and a hard-to-soft hardness ratio greater than 0.7: 

SELECT TOP 1000
m.name, m.significance, m.flux_aper_b, m.powlaw_gamma
FROM master_source m
WHERE (m.significance > 10.0 AND m.pileup_flag = 0 AND m.hard_hs > 0.7)
[NOTE]
Note

The query has changed from CSC 1.1 since the power-law slope is now m.powlaw_gamma rather than m.alpha.

See the CSCview threads for more examples.

—using command-line tools:

To non-interactively access the properties of the catalog through a URL, command-line tools such as cURL and GNU Wget may be used with the same query syntax as CSCview. cURL and Wget are utilities which allow the user to retrieve files with URL syntax from the command line, simulating the user's actions at a web browser. Examples include:

  1. To perform a basic property search query from the command line: 

    unix% curl --form query='SELECT TOP 1000 m.name, m.significance, m.flux_aper_b, m.powlaw_gamma FROM master_source m WHERE (m.significance > 10.0 AND m.pileup_flag = 0 AND m.hard_hs > 0.7)' http://cda.cfa.harvard.edu/csccli/getProperties

    unix% wget -O out.file 'http://cda.cfa.harvard.edu/csccli/getProperties?query=SELECT TOP 1000 m.name, m.significance, m.flux_aper_b, m.powlaw_gamma FROM master_source m WHERE (m.significance > 10.0 AND m.pileup_flag = 0 AND m.hard_hs > 0.7)'

  2. To perform a basic cone search query from the command line: 

    unix% curl --form query='SELECT m.name, m.ra, m.dec, m.flux_aper_b FROM master_source m WHERE dbo.cone_distance(m.ra,m.dec,83.77333,-5.68464)<=10' http://cda.cfa.harvard.edu/csccli/getProperties

    unix% wget -O out.file 'http://cda.cfa.harvard.edu/csccli/getProperties?query=SELECT m.name, m.ra, m.dec, m.flux_aper_b FROM master_source m WHERE dbo.cone_distance(m.ra,m.dec,83.77333,-5.68464)<=10'

  3. To upload a query to the URL (in this example the query is stored in the file cscquery.adql): 

    unix% curl --form query=@cscquery.adql http://cda.cfa.harvard.edu/csccli/getProperties

  4. To specify how a "missing" catalog value should appear in a table of query results (e.g., instead of a blank space, the word NULL is used): 

    unix% curl --form nullAppearance=NULL --form query="SELECT TOP 50 o.obsid, o.obi, o.region_id, o.theta, o.mjr_axis_raw_s FROM observation_source o, stack_source s WHERE (o.instrument = 'ACIS' AND o.theta < 0.5 AND o.edge_code = 0 AND s.detect_significance_b > 10.0 AND o.pileup_warning < 0.1) ORDER BY theta DESC" http://cda.cfa.harvard.edu/csccli/getProperties

  5. To change the output coordinate format for the RA and DEC columns to decimal degrees (from the default sexagesimal format): 

    unix% curl --form query="SELECT TOP 1000 m.name, m.ra, m.dec FROM master_source m WHERE (m.significance > 10.0 AND m.pileup_flag = 0 AND m.hard_hs > 0.7)" --form coordFormat=decimal http://cda.cfa.harvard.edu/csccli/getProperties

    unix% wget -O out.file 'http://cda.cfa.harvard.edu/csccli/getProperties?query=SELECT TOP 1000 m.name, m.ra, m.dec FROM master_source m WHERE (m.significance > 10.0 AND m.pileup_flag = 0 AND m.hard_hs > 0.7)&coordFormat=decimal'

Results Interface

Once a catalog query has been entered and the Search button selected in the Query tab, the Results tab automatically opens, displaying a table of search results and a list of data products available by CSC energy band. In the event that a submitted query takes too long to process, the Stop button may be utilized to terminate the query.

Results Tab

The columns of the query results table correspond to the source properties entered into the Result Set window in the Query tab (or specified between SELECT and FROM in an ADQL SELECT statement in the ADQL view), sorted as specified in the Sort Order window of the Query tab. The table may also be sorted in the Results tab by clicking on the header of the column by which the table should be sorted; clicking a second time sorts in the reverse order. Only the properties of sources which satisfy the Search Criteria specified in the Query tab are listed in the results table. If the 'Select: all' option was set in the Query tab prior to query submission, and multiple pages of query results are found, the full set of results may be viewed by moving the scroll bar to the right of the query results table up or down. The complete table of search results may be saved to a text file—in Tab Separated Values (TSV) or VOTable TABLEDATA format—by selecting the Save option in the File pull-down menu at the top of CSCview. If you wish to quickly save the results of a catalog search to a file without having to leave the query interface—i.e., without the Results tab automatically opening after the Search option is selected—the 'Save results to file' box above the Sort Order window should be checked while the Query tab is open, before conducting the search.

The cell widths of the query results table may be adjusted by dragging the cell boundaries with a mouse cursor; double-clicking a boundary resets the width to the default size. The table columns may be dragged to the left or right to rearrange the column order.

[NOTE]
Note

Query results stored in the Results tab will be lost if you re-visit the Query tab and modify the original query which produced those results, even if a new search hasn't been conducted; this is a security measure put in place to ensure the user always has a set of results consistent with the query form.

Source Preview

[NOTE]
Note

The source-preview functionality is not available for the live release of CSC 2.0. It will be added once the full release of CSC 2.0 has been made.

Data Products

After a query has been submitted, the full list of data files available for each source found in the search appears in the Data Products window on the left side of the Results tab. To browse or download files, at least one filetype, one energy band, and one row of the query results table must be chosen before submitting the data products query with the Search button. More than one filetype or row may be selected at a time simply by checking all relevant checkboxes.

In CSC2, while the type of data products returned by CSCview is uniquely determined by the selection made by the user in the left panel of the Results tab, the number of data products will vary depending on the type and number of identifiers present in the row(s) selected in the returned table of properties, for which the data products are being retrieved. CSCview will return all data products that can be unambiguously associated to the first available identifier in the following hierarchy:

  1. master source (name) if present, else
  2. stack source (detect_stack_id,region_id) pair if present, else
  3. observation source (obsid,obi,region_id) tuple if present, else
  4. stack (detect_stack_id) if present, else
  5. observation (obsid,obi) pair if present, else
  6. return an error indicating no identifiers are present in the Results table.

In other words, CSCview will return the most comprehensive set of data products, regardless of whether they are defined at the master source, stack or single observation level, associated to the highest-level identifier(s) available, ranked as listed above. For example, if a master source name is available in the selected row and the user selects a single observation-level data product, CSCview will return one data product for each of the single observations contributing to the master source even if lower-level identifiers are also available in the selected row of the table (Figures 1 and 2). Instead, if a master source-level data product is selected and the only available identifiers are the obsid and obi, CSCview will return the selected data products for all master sources associated to the observation determined by the values of the obsid and obi. The order of the identifiers in the selected rows of the table of source properties is not considered.

Query Results

[Thumbnail image: CSCView query results]

[Version: full-size]

[Print media version: CSCView query results]

Query Results

Results tab of CSCview showing the results of a CSC2 query that returns the following identifiers: master source name, stack detect_stack_id and obsid and region_id for all observation level detections of the master source. The user selects only one row from the Results tabs (red box) and one region data product from the master source (blue box) list, stack-level detection list (yellow box) and observation-level detection (black box) list in the Data products tab.

Query Data Products

[Thumbnail image: CSCView query data products]

[Version: full-size]

[Print media version: CSCView query data products]

Query Data Products

List of data products returned by the query shown in Figure 1. CSCview returns all data products unambiguously associated to the highest-level identifier available in the selected row from the Results tab, the master source name. In this case, 1 master source data product (blue box), two different stack-level detections data products (yellow box) and four observation-level data products (black box) are returned.

Products Tab

The filenames of all data products selected in the Results tab, along with file type and size, appear in the Products tab after the Search button has been selected in the Results tab. Here, the files may be downloaded individually, or together to a single tar file (by selecting the Download button in the toolbar), or via a download script for a batch download on the Unix command line (by selecting the Script button). Decompressing the tar file output by the Download option produces a directory which starts with the name "cdapackage...", which contains the downloaded data products compressed with gzip (Windows users should refer to the GNU zip website for .gz decompression options). The download script output by the Script option contains a list of GNU Wget commands, one for each file, which can be executed on the command line for a batch download of the selected files.

There are five pull-down menus at the top of CSCview (File, Edit, View, Tools, Help), the contents of which apply to whichever view is currently active: either the query interface (the main form or ADQL form of the Query tab) or the query results interface (Results tab or Products tab). For example, the Save option in the File menu will save to a text file either the query specified in the Query tab or the results contained in the Results tab, depending upon which tab is open.

The File menu contains the following options: New, Open, Export, Save, Search, Stop, Send, Download, Script, Reset, and Quit.

The New→Empty Query option clears the Query tab of its current selections so that a new query may be entered. The New→Default Query option first clears the Query tab of its current selections, then populates the form with the default standard query (Master Source Basic Summary).

The Open option allows you to upload a text file to which a previous CSCview query has been saved, either a .prop query save file output by the File→Save option, or a .adql query save file generated by the File→Export option. A .prop query save file should be loaded into the main form of the Query tab, while a .adql query save file is meant to be opened in the ADQL view of the Query tab, accessible via the View→Query→Show Language option.

The Export option saves the ADQL version of the current CSCview query to a text file with extension .adql, independent of which view of the Query tab is open (either the main form of the ADQL view). The saved file may be later uploaded to the CSCview Query tab via the File→Open option when the ADQL view of the Query tab is open.

The Save option saves to a text file either a CSCview query or a table of query results, depending upon which tab is open. If this item is selected from either the main form or ADQL view of the Query tab, the current query is saved to a file with the .prop extension; to save the ADQL version of the query, use the File→Export option. If selected from the Results tab, the Save item saves to a file the table of query results that appears after query submission. The available file formats for a saved table of search results are Tab Separated Values (TSV) and VOTable TABLEDATA, the latter of which is IVOA-compliant and allows for easy and flexible exchange of astronomical tabular data. To convert a TSV format save file to a CIAO-compatible format, see the CSC thread "Using a CSC Save File in CIAO".

[NOTE]
Note

Source properties with a catalog value of NaN/NULL appear as blank entries in a TSV-format file to which query results are saved. You may specify how Nan/NULL is represented in a TSV-format output results file with the Edit→Preferences menu option (or by using a command-line tool such as cURL; see Example 4 on the CSC Command Line Interface page).

The Search item queries the catalog database for source properties when selected from the Query tab, and data products when selected from the Results tab. In the event that a submitted query takes too long to process, the Stop button in the toolbar may be utilized to terminate the query.

The Stop option cancels a query or download which is currently in progress, depending on which tab is open and which action has been taken.

The Send option allows you to send the entire search results table in the Results tab to a remote client (e.g. TOPCAT) via a SAMP connection, and receive back a set of selections from the remote client. After the full table of search results has been transmitted, row selections from the table mey be sent as either highlights or coordinates. A data product file may also be sent from the Products tab (note that TOPCAT cannot receive FITS images).

  • Data sent from the Results and Products tabs can be mixed; e.g., you can send a FITS image from the Products tab to DS9, then go back to the Results tab and select 'Send Row Selections As Coordinates', and see them displayed on the image in DS9.
  • In order to communicate via SAMP, a SAMP hub is needed; CSCview does not start one. For example, to send CSC search results to TOPCAT, one would first open TOPCAT, then start a SAMP hub within TOPCAT (as shown in the thread "Sending CSC Data to Remote Clients with CSCview"), then start CSCview.

The Download item allows you to download data products selected in the Products tab, either individually, or multiple selected data products to a single tar file.

The Script item generates an text file of GNU WGet commands, one for each data product listed on the Products tab, to be used as a download script. This file may be executed on the Unix command line for a batch download of the selected files.

The Reset item reloads CSCview, regardless of which tab is currently open; it effectively quits and restarts the application. It clears the Query tab of its current selections and loads the startup query, and resizes any vertical and horizontal bars which were adjusted. The default startup query form can either be empty, or display a standard query; this preference is set with the Edit→Preferences→Startup Query menu option.

The Quit item allows the user to exit the CSCview session; the user is prompted with the message 'Are you sure you wish to quit this application?' before the GUI is closed.

The Edit menu contains the familiar text editing items Cut, Copy, and Paste, as well as Preferences.

Under the Edit→Preferences menu:

  • The Null Value Representation item allows you to specify how a catalog value of NaN/NULL should appear in a saved table of query results, instead of the blank entries which appear by default in the RDB-style file to which query results are saved.
  • You may select Sexagesimal or Decimal from the Output Coordinate Format item to specify the output coordinate format for ra*/dec* source property values in a table of query results.
  • The Floating Point Format item is used to specify how source property values should appear, in default or native format. The native catalog format includes numbers with many significant digits, exactly as they are output by the catalog processing pipeline, while numbers in the default format are truncated.
  • The Source Preview menu option is not available with the current version of CSCview for CSC 2.0.
  • The Startup Query item provides control over the contents of the query form upon startup: either it should be empty (None), or display the 'Master Source Basic Summary' standard query.
  • The Toolbar Appearance feature provides user control over the style of the toolbar display for ease of use; the choices are Icons and Text, Icons, and Text.
  • The Startup Help menu option provides the option to either hide or display the Getting Started guide when CSCview is opened.

The View menu contains two items: Query and Properties.

The Query→Show Language option allows the user to switch from the standard view of the Query tab to the ADQL view, where ADQL 2.0 query expressions may be entered; Query→Return to Form restores the standard view of the Query tab.

The Properties item allows you to specify the visual sorting of the source properties listed in the Source Properties window of the Query tab. The sorting can be done By Group, e.g. Source Fluxes, Source Variability, etc.; By Band, science energy band u, s, m, h, b, or w; or By Name, alphabetically by source property or data product name.

The Download Manager menu item opens a window displaying the filename and filesize of each data product downloaded from the Products tab, as well as the progress of the download. The window can be cleared with Edit→Clear or closed with File→Close. The Stop option cancel a download in progress, and the Info feature displays the full path of the file downloaded; the start and end times of the download, the number of bytes downloaded.

The Help menu contains a link to this web page (CSCview Help), which describes the functionality of CSCview, along with links to the CSC homepage; an About CSCview section containing CSCview version information; and a Getting Started guide. The Getting Started guide provides a brief overview of the features on each tab of CSCview, as well as a set of instructions for loading standard queries and building custom queries. The Edit→Preferences→Startup Help→Getting Started menu option can be set to have this guide automatically pop up when CSCview is opened.

Status bar

The status bar at the bottom of CSCview records a dialog of key actions and any errors which have taken place before, during, and after query submission, such as: Query loaded, Searching, Search completed: 50 rows found, Query failed validation, and so on.

Metadata Display

The metadata display at the bottom of the Query and Results tabs lists the name, data type, units, and description of source properties selected in any of the the fields in the Query tab when the Query tab is open, and the product type, product specifier, format, and description of each data product selected in the Results tab when the Results tab is open. The metadata display does not appear on the Products tab. For extended, high-level descriptions of each source property and data product included in the catalog, see the "Catalog Columns" and "Data Products" pages.

/ csc / gui / intro.html