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 two categories: Master Source properties 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 catalog release - as well as catalog releases, which are carefully reviewed, static versions of the CSC. As of August 2010, Releases 1.0.1 and 1.1 are available.
OS X 10.8: In order to run CSCview on this platform, the
following steps must be taken; otherwise, you will not be able
to launch CSCview.
1) Go to System Preferences and select "Security & Privacy."
2) Under the General tab, change "Allow applications downloaded from:" to "Anywhere."
OSX 10.9 (Mavericks): Changes in the OSX firewall may cause
the CSCView application to hang for upto 10 minutes before
loading. Users can avoid this by disabling "Stealth Mode"
1) Go to System Preferences and select "Security & Privacy."
2) Under the Firewall Options, uncheck the "Enable Stealth Mode" option.
Linux users: in a default installation of the Linux operating system, you may not have support for Java applets. See the Software Requirements page for details.
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.
Questions about CSCview should be submitted to the CXC Helpdesk.
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.
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.
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.
- Select one of the example queries listed in the "Standard Queries" 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.
- 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 interacive 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.
To quickly start a query in the Query tab of CSCview, simply select one of the "standard queries" provided and drag it to any area on the query form; this will automatically populate the interactive windows with example entries. 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 contained within the field.
Many example queries are available as search templates in the Standard Queries 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 a Master Source Basic Summary, Master Source Summary, Master Source Photometry, Master Source Variability, Source Observation Summary, Source Observation Photometry, and Source Observation Variability. The "Master" queries return properties from only the Master Sources Table, while the "Observation" queries include a mix of properties from the Master Sources Table and Source Observations Table. All standard queries automatically add the 'dataset_id' column to the Result Set window, so that data products may be downloaded for sources returned by the query (see the Source Properties section for more details).
The Standard Search Criteria section of the Standard Queries window consists of two options: Search by Observation Identification and Search by Variable Sources. When the first option is added to the query form, the 'o.obsid' source observation property is entered into the Search Criteria window so that you may enter a Chandra ObsID by which to search. When the second option is selected, a set of search conditions specific to source variability analysis are entered into the Search Criteria window. To run this query, be sure to add at least one source property to the Result Set window.
Source PropertiesThe source properties listed on the Query tab of CSCview are categorized into four groups: Master Sources, Source Observations, Master Sources/Source Observations Associations, and Data Products. These represent the "columns" of the catalog tables, i.e., source quantities or parameters that are officially part of the catalog. 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. 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 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 CriteriaThe 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 ('o.targname LIKE "SN%"' in the ADQL interface).
- _ 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 ('o.targname LIKE "NGC 001_"' in the ADQL interface).
- [p-s] matches single characters in the range 'p' through 's'
For example, 'o.targname LIKE [p-s]%' matches source target names which start with 'p' through 's', followed by any set of characters. ('o.targname LIKE "[p-s]%"' in the ADQL interface).
- [aghz] matches exactly one of a, g, h, or z
For example, 'o.targname LIKE [aghz]%' matches source target names which start with 'a', 'g', 'h', or 'z', followed by any set of characters ('o.targname LIKE "[aghz]%"' in the ADQL interface).
- [^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 ('o.targname LIKE "[^p-s]%"' in the ADQL interface).
- [^agkm] matches 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 ('o.targname LIKE "[^agkm]%"' in the ADQL interface).
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'. Though the 'match_type' column can only be entered once; 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 SetTo 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 resolved into one or the other. 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:
A VO Cone Searchservice 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):
- verbosity = 1 reports the source name, RA and DEC values from the Master Sources Table for each matching source resulting from the cone search
- verbosity = 2 reports the master source summary results and Space Time Coordinate (STC) metadata
- verbosity = 3 reports all the columns in the Master Sources Table
See example output in 'out.vot' produced by the Wget command above.
Position Search: CrossmatchThe 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.
- 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.
Please 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 seven 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', 'obi_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.alpha FROM master_source m WHERE (m.significance > 10.0 AND m.pileup_flag = 0 AND m.hard_hs > 0.7)
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. For example:
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.alpha 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.alpha 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:
% curl --form query=@/tmp/cscquery.adql 'http://cda.cfa.harvard.edu/csccli/getProperties'
4. To specify how a catalog value of NULL should appear in a table of query results (e.g., instead of a blank space):
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 obi_source o WHERE (o.instrument = 'ACIS' AND o.theta < 0.5 AND o.edge_code = 0 AND o.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% 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'
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
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 (including a Source Preview feature) 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 TabThe 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: 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.
Each row of a table of search results includes a clickable "View" button for accessing Source Preview, a feature which allows you to view source region and full-field images of the source in the selected row. The source region images available in Source Preview include a tricolor soft-medium-broad (red-green-blue) events image, a single-color events image in any of the selected CSC energy bands (ultrasoft, soft, medium, hard, broad, wide), and a PSF image in any CSC energy band. The full-field broad-band events image is available at different blocking factors (image resolution); they are 1, 2, and 4 for ACIS data, and 2, 5, and 12 for HRC data.
The image displayed in Source Preview may be saved to a JPEG file by selecting File->Save within the Source Preview window. Multiple windows may be opened simultaneously by setting the Edit->Preferences->Source Preview->Opens in New Window menu option, or by holding down the Shift key while pressing "View" for each source which should be displayed. Note that Source Preview is only available when the 'dataset_id' catalog column is included in the search results, as this property is used to uniquely identify the set of data products associated with each source.
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. Note that the 'dataset_id' catalog column must be present in the search results in order to retrieve data products for catalog sources, since this property is used to uniquely identify the set of data products associated with each source.
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 named "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.
FileThe "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).
- 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.
EditThe "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 controls what happens when the 'View' button is selected in a row of a table of search results in the Results tab, to open the Source Preview of the corresponding source. The 'Open in Same Window' setting will replace the source image displayed in the Source Preview each time the View button is clicked for a source; 'Open in New Window' will create a new Source Preview window each time the View button is clicked. Furthermore, if the Shift key is held down while pressing View, a new window will be created.
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.
ViewThe "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.
HelpThe 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.
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.
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 of the CSC website.