Last modified: 4 October 2019

URL: https://cxc.cfa.harvard.edu/csc/threads/gui_samp/

Sending CSC Data to Remote Clients with CSCview

CSC Threads


Overview

Synopsis:

This thread provides step-by-step instructions for sending CSC data returned by a CSCview query to remote clients, as well as receiving data from remote clients, using the SAMP connection in CSCview. SAMP, an acronym for Simple Application Messaging Protocol, is an application which allows catalog data, including FITS images, to be exchanged among multiple stand-alone applications which support it, such as CSCview, DS9, and TOPCAT.

The Send menu option in CSCview allows you to transmit a table of source properties from the Results tab to another application which supports SAMP, as well as data product files associated with sources, from the Products tab. It also enables you to receive a table of data from a remote client into the User Table→Received Table field of the crossmatch feature of the CSCview Query tab.

Last Update: 4 Oct 2019 - updated for CSCview version 2.0


Contents


Introduction

A simple and quick way to send CSC source data to remote clients which support a SAMP connection has been made available with CSCview in release 1.1 of the CSC. The new Send menu option in CSCview allows you to transmit a table of source properties from the CSCview Results tab to a remote client, and receive back a set of selections from the remote client. Data product files, such as events images, may also be sent from the CSCview Products tab to another application. For example, a broad-band events image of a Chandra source field may be sent to DS9 for display, then a table of search results including the positions of CSC sources in that field may be sent to the DS9 Catalog tool to have the source regions overlaid on the uploaded image. In a similar way, CSC data may be sent to TOPCAT from CSCview (or DS9) for data manipulation and visualization, e.g., to plot a histogram or a 2D scatter plot of column-based quantities, using any combination of CSC source properties.

In order to exchange data amongst multiple standalone applications which support SAMP, one of the applications must be equipped with the capability of starting a SAMP hub; neither CSCview nor DS9 has this capability, for example, but TOPCAT does. Therefore, in order to send CSC data from CSCview to both DS9 and TOPCAT, a SAMP hub should be opened in TOPCAT before starting either CSCview or DS9.

Keep in mind as we follow the steps in the example below that CSCview, TOPCAT, and DS9 can all talk to each other via SAMP in a 3-way conversation, so to speak. In other words, data can be transmitted in all directions as seen from each application, and an action in one application creates a simultaneous action in the remote applications. For example, with the appropriate settings in place, clicking on a data point in a TOPCAT scatter plot highlights the corresponding row in the table of search results in CSCview, as well as in the CSC data table in the DS9 Catalog tool (the selected source also appears highlighted and centered in the DS9 image display).


Demonstration

Here is a QuickTime screenshot movie (4.7 MB) which demonstrates the set of instructions provided below. To run the .mov file, please be sure you have the appropriate plug-ins and software installed for your web browser and operating system.

[]
[NOTE]
Note

The CSCview GUI appears different in the movie than the GUI shown in the snapshots below; this is because:

  1. the GUI in the movie was run on a Mac operating system (dark gray), while the GUI in the screenshots was run on Linux (pale gray with blue)
  2. the GUI in the movie accesses the CSC release 1.0.1 database, while that shown in the screenshots accesses CSC release 1.1, the most recent release
  3. the GUI in the screenshots shows CSCview version 1.1.1, while that in the movie shows version 1.1

Open an application which can start a SAMP hub

Open TOPCAT and start a SAMP hub

Since neither CSCview nor DS9 is equipped with the capability of starting a SAMP hub, we open TOPCAT and click the SAMP Status button ([]) in the TOPCAT GUI to start one. Clicking the Connect/Disconnet icon in the SAMP Control window provides the option to select an internal or external hub. An internal hub runs in the same Java Virtual Machine as TOPCAT itself, and an external hub runs in a separate process. An internal hub will shut down when TOPCAT does, while an external hub will keep running until it is explicitly shut down.

[]

Open the other SAMP-enabled applications

Open DS9 and CSCview

With TOPCAT and a SAMP hub up and running, we now open the other applications which will communicate with TOPCAT via SAMP, DS9 and CSCview.


Exchange data amongst the stand-alone applications via SAMP

Build a CSCview query

We consider the example of querying CSC release 2 in CSCview for all bright X-ray sources within 1 arcminute of the center of the Andromeda Galaxy (M31), and then sending the data returned for those sources to both DS9 and TOPCAT.

We begin the query by selecting "Release 2.0" in the Catalog tab, and then clicking "Search" to open the Query tab. After clearing the startup query with the "New→Empty Form" toolbar option, we enter "M31" in the "By Name→Name" field of the "Cone search" field to conduct a position search, specifying that we wish to locate the sources within 1 arcminute of the coordinates returned for M31. An additional search criterion is entered into the Search Criteria field, specifying that all sources located within 1 arcminute of M31 must also have a total of at least 150 broad-band counts (0.5-7 keV) in the source plus associated background region. Finally, we choose to have the properties contained in the Master Source Photometry Summary returned for all sources located by the query.

The table of search results is returned in the Results tab after clicking "Search" in the Query tab, sorted on the 'separation' property, which is automatically added to the result set of a cone search query (which we copied to the Sort Order field in the Query tab). The data product files associated with the sources returned by the query are browsed and selected in the Results tab, and returned in the Products tab. (To learn more about building queries in CSCview, refer to the CSC threads and the CSCview help page.)


Send Catalog Data to DS9 from CSCview

Once the CSCview query is submitted and the Results tab opens with a table of search results, we can send the table to the remote clients connected to CSCview by clicking the "Send" button. We can also make our data product selections in the Results tab for any or all of the sources in the results table, and access those files in the Products tab by clicking "Search" in the Results tab.

In this example, we choose to first send a full-field, stack image in the broad band of one of the six sources closest to the center of M31 to DS9 for display. We do this by selecting a row in the table corresponding to a source with the second smallest separation from the central coordinates of M31, and then making our data product selections for this source. Submitting this query opens the Products tab with a list of our selected files. We select the broad-band, full-field stack level image, and then click "Send→SAOImage DS9"; the image then open in DS9.

Next, we switch back to the Results tab in CSCview to send the entire table of source properties to DS9, in order to have the positions of those sources overlaid on the image.


Send Catalog data to TOPCAT from CSCview

In order to send CSC source data to TOPCAT to create a 2D scatter plot, for example, we select the table of CSC source properties in CSCview and then "Send→topcat". This action populates the Table List in the TOPCAT GUI with an item indicating the loaded table of source data (cscresults.1.vot); clicking on the table name in the Table List opens the table of data in a separate Table Browser window.

In this example, we choose to create a 2D scatter plot of the CSC source properties flux_powlaw_aper_b and flux_bb_aper_b, which represent the power-law and black-body aperture model broad-band energy fluxes. This is achieved by clicking the TOPCAT Scatter Plot icon, and then selecting the two columns of data from the table we wish to plot along the x and y axes.


Send Catalog data to TOPCAT from DS9 and vice versa

In order to send a table of CSC data from the DS9 Catalog tool to TOPCAT, we would simply click the "SAMP" button at the bottom of the DS9 window. Individual row selections within the table in the DS9 Catalog Tool automatically appear in TOPCAT, without clicking the "SAMP" button. Note that we can also select a source in the DS9 image display to have it simultaneously highlighted in a TOPCAT table or plot (as well as in the CSCview results table).

To have our TOPCAT source selections appear in DS9, we must set a TOPCAT 'Activation Action' in the TOPCAT GUI. The Transmit Row item of this feature lists 'Target Applications', including 'SAOImage DS9'; select this option, and then sources in a TOPCAT plot or table. A selected source appears highlighted and centered in the DS9 image display.

To view a demonstration of this functionlity, see the CSC thread Accessing the CSC with DS9 and TOPCAT.


Receive a table of data into CSCview crossmatch query

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 User Table→Received Table option can be used 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.


History

11 Aug 2010 original version
24 Nov 2010 updated for CSCview version 1.1.1
04 Oct 2019 updated for CSCview version 2.0