Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: 29 November 2017

URL: http://cxc.harvard.edu/csc/gui/intro.html

CSCview and CSC 2.0 Help


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

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 November 2017, the Current Database - which is updated as observations are processed by the CSC 2.0 pipeline - is available, along with the (static) releases for versions 1.1 and 1.0.1. The CSC status page has more details.

[IMPORTANT]
The default database for CSCview is Release 1.1

The default database used by CSCview is Release 1.1; the Catalog tag should be used to change the version to Current Database. The label in the Query tag will update to reflect the chosen database.

[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

or, for users with Java 9:

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. 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.

The default is set to Release 1.1, so it has to be changed to Current Database to access the CSC 2.0 data.


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

Custom Query

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 "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 ontained 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".

[CAUTION]
Caution

The descriptions of the standard queries has not yet been updated to match those provided for CSC 2.0 (in particular, there is limited mention of Stack Properties, which are new to CSC 2.0).

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 Source Observations Table respectively.

The Standard Search Criteria section of the Standard Results window consists of three options: Search by Stack Identification, Search by Observation Identification, and Search by Variable 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.

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 source observation properties are those which result from an individual observation (Obi) of a source, and are recorded in the Source Observations Table.

The Master Sources/Source Observations Associations group contains the 'match_type', 'is_primary', 'msid', and 'posid' columns. 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. 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 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 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.) See the thread "Using Source Property Associations" for a demonstration of the use of the 'match_type' catalog column.

The 'is_primary' column returns a Boolean value of True or False to indicate if a source observation represents the 'primary' observation chosen from multiple observations of the same source. A primary source observation represents the 'best' observation of a source, therefore its properties are key in determining the master source properties for that source. If a master source is associated with only one unique source observation, this observation is the primary.

The 'msid' and 'posid' columns contain the identification numbers of each master source and source observation entry in the catalog database, respectively, which are used to associate source observations with master sources.

The Data Products category contains the 'msid' and 'posid' columns also contained in the Master Sources/Source Observations Associations category (described above), in addition to the 'dataset_id' column, which is used to access data products from the archive. Each dataset_id corresponds to a complete set of products for each source observation entry in the catalog. The data products which are accessed for a master source are those which are associated with the primary source observation for that master source. Note that in order to download data products for catalog sources, the 'dataset_id' column must be included in the result set of a query (it is there by default in CSCview startup and standard queries).

The collective group of source properties is presented in a hierarchy in which each category - Master Sources, Source Observations, Master Sources/Source Observations Associations, and Data Products - may be sorted by scientific group (e.g. Spectral Properties, Source Fluxes, etc.), science energy band, or alphabetically by name. The ordering may be set by expanding the "View-->Properties" menu option and choosing either "By Group", "By Band", or "By Name". For extended descriptions of each source property in the CSC, see the catalog column descriptions.

Search Criteria

The Search Criteria window of CSCview accepts master source properties, source observation properties, master sources/source observations association properties, and data product properties to be used as the search conditions for a database query. 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, >100,000 sources.) 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 are prefixed with 'o.' in the Search Criteria window to be distinguished from master source properties. Once the source properties have been added, you have the option to set each property 'equal to', 'not equal to', 'greater than', 'greater than or equal to', 'less than', or 'less than or equal to' 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:

% matches any set of characters

For example, 'o.targname LIKE SN%' matches source target names which begin with "SN", followed by any set of characters.

_ matches exactly one character

For example, 'o.targname LIKE NGC 001_' matches source target names which begin with "NGC 001", followed by any single character.

[c-h] matches single characters in the range c through h

For example, 'o.targname LIKE [p-s]%' matches source target names which start with 'p' through 's', followed by any set of characters.

[agh] matches exactly one of a, g, or h

For example, 'o.targname LIKE [aghz]%' matches source target names which start with 'a', 'g', 'h', or 'z', followed by any set of characters.

[^p-s] matches single character that is NOT p through s

For example, 'o.targname LIKE [^p-s]%' matches source target names which do not start with 'p' through 's', followed by any set of characters.

[^agkm] matches a single character that is NOT a, g, k, or m.

For example, 'o.targname LIKE [^agkm]%' matches source target names which do not start with 'a', 'g', 'k', or 'm', followed by any set of 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 combine source observation 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 source observation properties may return the same set of source observation 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.

Position Search: Cone Search

-- within the GUI:

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 source observations 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:
[NOTE]
Note

The VO Cone Search service will not be available for CSC 2.0 data until the full release in February 2018. The ADQL command-line interface can be used to search the database for a location.

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 and 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

[CAUTION]
Caution

The description of the available tables and columns for ADQL queries has not been fully updated to match those provided for CSC 2.0. In particular, there is limited discussion of Stack Properties, which are new to CSC 2.0.

-- 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:

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:
[CAUTION]
The version=cur option must be set when using the command-line interface

The version=cur option must be used when using the command-line interface - i.e. any access to http://cda.cfa.harvard.edu/csccli/getProperties - otherwise the CSC 1.1 catalog will be used.

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)' --form version=cur 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)&version=cur'
    
  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' -form version=cur 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&version=cur'
    
    [NOTE]
    Note

    Since the source-properties pipeline for CSC 2.0 has not been run on all observations, the query may return no matches because the area of sky has yet to be processed, rather than because the source has not been detected. The catalog-coverage section of the "Is my favorite source in the Chandra Source Catalog 2.0" page provides more information.

  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 --form version=cur 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" --form version=cur 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 --form version=cur 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&version=cur'
    

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.


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.


Menus

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.

File

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: 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).

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.

Edit

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

The Preferences -> 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 Preferences -> Output Coordinate Format item to specify the output coordinate format for ra* / dec* source property values in a table of query results.

The Preferences -> 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 Preferences -> Source Preview menu option is not used with the live release of CSC 2.0.

The Preferences -> 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 Preferences -> 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 Preferences->Startup Help menu option provides the option to either hide or display the Getting Started guide when CSCview is opened.

View

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.

Tools:

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.

Help

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.


Last modified: 29 November 2017
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.