The Xamin Web Interface

This document describes how to use the Xamin web interface. The first part of the document is a tutorial working through example queries that illustrate the major features of Xamin. The following sections comprise a comprehensive reference manual which discusses each element of the web interface.

Additional information on Xamin is available in other documents. If you would like to view short how-to videos of the web interface, take a look at the Xamin Introductory Page. If you want to use Xamin capabilities outside of the web/browser environment take a look at the Xamin CLI Guide. If you are interested in the overall architecture of Xamin, the Xamin System Guide can help.

An Xamin Tutorial

When you start an Xamin web session your browser should show a form that looks like

This form allows you to select tables, specify search constraints and initiate queries. Many of its features are dynamic. In this tutorial we'll work through a series of increasingly complex examples. Detailed screenshots illustrate how you can use the system. If you try these examples you'll get a taste of many of Xamin's capabilities. The Xamin web interface is under development and the appearance can change a little from browser to browser, so the screen shots may be slightly different from what you'll see.

The example queries we'll try are:

What tables have information about 3C273?

When you aren't sure where to start, a question you can begin with is whether there is any information on a target of interest. If there is you may want to browse. Let's try this for the much observed quasar 3C 273.

To discover what tables have information about 3C 273 or another source or position is as simple as 1, 2, 3...
  1. Enter the target you are interested in in the Position box.
  2. Click on the Find matches in... All HEASARC Tables button.
  3. A new query results pane showing the tables that have information on 3C 273 pops up.
This kind of query, where we're finding out which tables match generic constraints is called a discovery query .

Note how the Find matches in... box becomes active as soon as you start typing in the position (or start time) field. Xamin can't 'find' anything until you tell it what to look for. This discovery query takes a little while. It's looking at all HEASARC tables, for each using a default radius appropriate for that table.

3C273 Discovery Query

In the result pane each row shows a table name, the number of rows matched, and the title of the table. If the table has an associated mission, wavelength regime or if it specializes in a particular class of objects, that's shown too.

Xamin shows the results of each query in a new result pane rather than popping up new browser windows. In only a few cases, e.g., displaying this help page does Xamin actually create a new window in the browser (or new tab if you are using tabbed browsing). You may find maximizing the Xamin window makes it easier to keep track of everything since a lot of panes can be visible at once.

You can sort your results by any column just by clicking on the column headers. The initial default order is just the alphabetical list of table names.

To see the matching rows from a particular table, you can click almost anywhere in the row. We scrolled down a bit and clicked on the chanmaster (1) and got a pane of Chandra results (2) and then clicked on dixon (3) rows which yielded a second query result (4).

Discovery query + two derived queries

The title bars on the panes identify the table that each pane is associated with. These are single table queries of the two tables we picked out at the position of 3C 273.

There's a bit more going on in the results from the Chanmaster table. Each row has a little '+' icon at the beginning. You can expand that to see data products associated with a row. The pane also has buttons on top for selecting the data products associated with selected rows. We show how to download products in the next example.

What observations has Chandra made of AM Her? How do you download the data?

In this example we'll explore how you select tables to query in Xamin, and then how you might retrieve data from a table of observations.

There are several different approaches to finding tables using the Xamin Tables Explorer:

Entering table names directly

If you know what the table name you want to query is you can just enter it in the box on the top left of the Tables Explorer. This is a combobox: a combination of a text entry field and a menu. You can treat it as a text entry box and type in the whole table name, or you can use it as a select/menu box and choose the table from a menu. Or a combination of both: type in the first few letters of the name and a menu of matching tables will show up. You can click on one of these at any time. E.g. below we've begun typing in 'chanmaster' and we can either finish or click in the list below. The list is automatically refined as we type in more.

table input box example

Searching the table hierarchies

If we're not quite sure of the table name, we may want to explore the hierarchies of available tables using the left side of the table explorer. If we're interested in Chandra observations, the 'Master observation tables' sounds promising, so we click on the open icon Open treeto open this node of the tree and see what's there. A quick scan shows that chanmaster lists observations for the Chandra mission.

If we click on the name we'll see the documentation for that table pop up in the Information pane at the bottom of the query window. We can click on the add, Add resource, icon next to Chanmaster to select that table. You can also drag the name and drop it into the selected tables box. Alternatively we might have started with the Missions tree but since there are currently about 90 tables associated with Chandra it might have been hard to pick out the right one. Or we could have looked inside Regimes/X-ray, but there are over 300 of those!

Whenever you see the Add resource, you can select all of the tables in that node in a single click. Then you can do a discovery query on just the selected tables. E.g., you can select all of X-ray tables and look for which of these have matches to 3c273.

Master observatation tables

Select tables through their descriptions

Sometimes we may not even have a guess of where to look for our table in the available table hierarchies. Then we can use the documentation search feature of the Tables Explorer. It uses the search box at the top right of the explorer. We know we are interested in Chandra observations, so
  1. We enter chandra observations in the "Search by keywords" box and hit return or the Search button adjacent.
  2. A search results pane pops up which shows matching table ordered by relevance. A bit of context from the documentation for the tables usually gives us information to decide if the table is of interest. The best matches are listed first.
  3. We can click on any row in these results and the full documentation for the table shows up in the Information area at the bottom of the query pane. So we can check to make sure we have the right table. In this case the top match, chanmaster, looks pretty good.

To select a table from the keyword search results, we can click on the add icon just as we did when looking at the category trees.

Continuing the query.

We've just discussed three different ways of finding a table. We can use any of them to get chanmaster into the selected tables list.

Regardless of what method you use, if you happen to select a table accidentally you can use the delete icon, delete, or double click on the table name in the Selected tables tree to de-select it.

Once you've selected the table (1), if you just want matches to a given target or position, enter the position in the position box (2) and click on the Query to ... Table (3) button. We get a new pane with three matching observations (4).


In this example say we're interested in data products for the HETG grating observation. We click on the row we're interested in (1) to highlight it and then ask for data products from the highlighted rows (2) by clicking on the appropriately labelled button. The products cart pane pops up (3) with our selected observation (5). We can ask to download the products as a Tar file (5). Your browser should start its usual dialog for saving a file on your system.

Chanmaster/AM Her

We didn't have to download the products right away. In an Xamin session you can accumulate products from multiple queries (possibly of different tables) and then download data whenever you are ready.

Note, if you wanted to look for specific data products you could either expand the products for a given row using the or use the Limit Products button to select a specific set of products for each row.

Finally, you don't need to download the data as part of your Xamin session. You can get use the product cart to build a Curl or Wget script which allows you to download the files directly onto your machine. This is the recommended approach for any significant download since it can easily be restarted in the middle if the download gets interrupted for any reason.

What targets have both ASCA and ROSAT observed?

Xamin makes it easy to run correlation queries, i.e., run queries that match multiple tables in position or other characteristics. Let's look at finding all of the positions that both ROSAT and ASCA have observed.

First we need to select the appropriate tables for the missions: We can use any of the methods we tried in the previous query. Since we are doing two observation tables, using the 'Master observation tables' tree node may be particularly attractive. The the Tables Explorer might look like


immediately after we select the rosmaster table. We just dragged the rosmaster and ascamaster entries into the selected tables area.

Correlations between two complete mission tables are likely to show a lot of results. By default Xamin only shows the first 100 rows of results. We want to see everything, so we go to the Query control menu (1,2) and clear the Max Rows limit -- or just set it to some very large number (3).


Just click in the box and fill it with a big number or leave it empty. You may need to click somewhere outside the menu to get it to close.

Our first iteration of this query is going to generate almost 20,000 rows of results. The Grid output format we've used so far is not very efficient in handling such large results. Also, the Grid format by default will look for the data products for all of those rows. That could take quite a while too. So if we stay with the Grid format our query is likely to time out.

aligned query prompt

Recognizing the problem, Xamin prompts us to see if we might prefer to try the Aligned text format whenever you disable the query row limit or set it to more than 500 rows. The Aligned text output format has no problem with large results and should probably be used whenever you are requesting more than ~1000 rows in a single query. However it does not link to data products. We accept Xamin's suggestion (1).

You can also set the format to Aligned Text and a number of other formats (e.g., FITS, VOTable, Excel) using the Options/Output Formats menu.

OK... We've dealt with an annoying subsidiary issue. What do we need to do to actually set up the correlation? It turns out that we don't need to do anything. As soon as we select two tables, Xamin sets things up to do the correlation. All we need to do is Query to...Correlate (1). In about 10 seconds we see a new pane pop up(2). It uses a simple text rendering of the results. If you want to set the correlation radius we talk about that a few paragraphs below.

options/aligned text

The ASCA columns are at the left of the table prefixed with a. If we scroll right we find the ROSAT columns prefixed wit b. If there were more tables in the cross-correlation we might have c and d prefixes as well.

Simple spatial correlations are fine, but we often want to put additional constraints on the query. E.g., we may only be interested in observations where the ROSAT observation is comparably deep to the ASCA one. To add any constraints to a query, other than position or time, we use the Parameters Explorer.

To open the Parameters Explorer we click on the '+' on the bar where it say "Set Parameters Constraints ..." page. Actually we can click anywhere on that bar (1). This area is available only when we have specified one or a few tables to query. Xamin limits correlations to 4 tables since larger correlations are likely to take a long time (let us know if you'd like to get around this!).

When we click here (1) the Tables Explorer collapses into a single bar, and the Parameters Explorer pops up. Only one of these two can be active at any given time. You can click on the Tables Explorer bar to get it to reappear if you want to change the table[s] you are querying.

The fields of the input tables are listed in the Parameter constraints area. If there are multiple tables, then each parameter is prefixed with a letter, a,b,c, or d corresponding to the 1st through 4th tables. So here a refers to ASCA and b to ROSAT.

At the very top of the Parameters explorer is a yellow line with a bit of mysterious content ||a,b|| < Dft . This line is the constraint that Xamin added for us saying that the offset between the rows in table a and and the rows in table b must be less that some default value -- the value depends upon the first table and generally represents the size of the observations or the uncertainty of the positions in that table. The value used is listed at the very end of the query results (in text format or viewed using the ? tool for a Grid output). You can edit this field and replace Dft with any correlation radius that you want -- expressed in arcminutes.

We'll add two contraints: We want to make sure the ASCA SIS observation is at least twice as long at the ROSAT exposure (2). The constraints we set on a row can include references to any rows in the participating tables, not just constants. We also put a minimum on the ROSAT exposure time (3).

cross-correlation of rosat and asca

When we re-execute the query (click on Query to... Correlate) the resulting table (2) has only a tenth of the rows of our original table (2). We scrolled to the end of each query to get to the query summary. By the bye, this illustrates one nice feature of Xamin: It's really easy to compare query results with one another since they show up in separate panes. Of course this means that you need to clean up those panes eventually.

filtered ASCA/ROSAT correlation

What is the average flux of RASS FSC sources as a function of galactic latitude?

You can do sophisticated manipulations of the data in Xamin. Here's an example that shows both some advanced querying and highlights Xamin's Plot capabilities. To get rid of anything we've set in the query pane, we just click on the Clear...All button near the top right of the form. Next we select the ROSAT All Sky Survey Faint Source Catalog (RASSFSC) as our table. You should know how to do that by now.

Setting up this query requires that we spend a bit of time in the Parameters Explorer area. So we click on the Parameters Explorer bar to bring up that area after we've selected the RASSFSC table.

When we start we see a set of parameters then a red bar (1) and then some more parameters. Fields above the red bar will be displayed, while those below will not. We can specify constraints on any row, displayed or not. We can drag and drop fields (one at a time or in groups) to specify the order in which to display results. We can drag the red bar to add or delete fields from the results (or equivalently drag other fields over the red bar).

Xamin allows users to add new tables to a column. In fact in this example we are going to run a query where all of the output columns are ones we add to the table. To add a column we need to click on the User-defined column button at the bottom right. This brings up a small pane that allows us to define a new column in the table.

column definition

We specify a name for the column avg_count_rate and ask for the average of the count_rate column for each group of rows in the output to be returned in this column using the SQL avg aggregate function avg(count_rate).

We repeat this for two more columns: The count column is defined as count(*), the number of rows in each group. Finally we define a column bii_bin as the largest integer smaller than the Galactic latitude using floor(bii). New columns can use a wide variety of SQL expressions and may involve multiple fields from the input tables.

After we've added all three new columns our Parameter Constraints area looks like:

Parameter Contraints/RASS FSC before

Our new fields are distinguished by color and are placed, by default at the top of the grid of output rows.

When you use aggregate functions in a query (e.g., avg and count), Xamin takes a look at the query and examines each of the output fields. It finds each of the output fields that are not aggregate functions and creates a query where for each distinct combination of these non-aggregate fields, the fields that are aggregate functions are computed. Consult a manual on SQL for more information on aggregate functions.

We want to compute the average flux in a Galactic latitude bin, so we want to suppress all of the other fields that are shown in a RASSFSC query by default. They would break up our simple latitude bins. E.g., if we left in the name field, then each of the rows that share the same latitude bin would have different names, so instead of one bin for each latitude bin, we'd have a separate bin for every distinct name in each latitude which would defeat the whole purpose of the query. To get rid of the unwanted fields we can drag the red bar from its original location to just under the three rows we've added. Now only these three columns will be returned in the output.

parameter constraints/three rows

Now we run the query... We get an output table that looks like:

rassfsc results unsorted

Clearly it would be more useful if we sort the output. We can do that in the Parameter Constraints as well. We enter the sort criterion floor(bii) in the box at bottom left.

adding a sort field

When we rerun the query we get the results in an order that makes sense

rassfsc results sorted

It would be much nicer to see this graphically. That's easy. Instead of clicking on Query to...Table we try Query to...Plot. A Plot Control pane pops up. This has lots of options, but we just

  1. Set the X axis to bii_bin
  2. Set the Y axis to avg_count_rate
  3. Request the plot.

plot control window

In a second or two we get a plot of the results.

plot window

If you look carefully, you might notice that the plot only seems to run from -90 < bii < 10. Why is that? We mentioned above that by default Xamin only plots the first 100 rows. That's true regardless of whether the output fields are found in the stored table, or generated dynamically as they are here. To get the entire sky we'd need to change this limit as we did in the previous example. There is a checkbox on the plot control pane which allows you to override this limit. You can also go into the Options menu to change the row limits. In recent versions of Xamin, you can also modify the query at the bottom of the query pane.

This almost looks like science. What's going on here? The ROSAT All-Sky Survey is not uniform. It's most sensitive at the ecliptic poles. The ecliptic south pole is at Galactic latitude -30. The north pole is off our plot at +30.

Which of the targets in my list have not been observed by XMM-Newton mission?

Around proposal time one of the interesting questions is often what targets have not been observed. If you have a list of interesting sources you may want to see if there are some that might merit a proposal. To do this we need to anti-correlate the observation table with our list. But first we need to get the list into the system. For that we need to have an Xamin account. If you don't have one it's easy to set up.

In the Session menu click on Login.

session/create account

This brings up a new window that allows you to specify your HEASARC services account.
login form

If you don't have an account, click the Create Account button to get
create account form

You'll need to specify a name, E-mail and password. When you are done, click submit and if there are no problems you'll get
create ack

You might need to pick another name if someone else already has the one you tried. The name should begin with a letter and contain only letters, numbers and the _ character.

After you get this acknowledgement you should receive an E-mail like:
create ack

Click on the first URL, or copy it into a browser window to activate the account. You should see a simple page
create ack

Your account is permanent unless you or the Xamin system administrators delete it. So you only need to set it up once and you can log in directly in all future Web sessions.

Now you are ready to login. Of course if you already have a HEASARC services account, you skipped down to here. Just do Session/Login and enter your name and password.
When you log into your account you'll see a number of capabilities in the session menu that used to be grayed out jave become active, notably the Upload (1) option. The user name in the query pane title bar should also change to your account name.
ungrayed session menu
Now that you have an account you can save files and use them to correlate with other tables. Uploads are supported for a few different formats, notably VOTables, TDAT files (a HEASARC internal format), and CSV files. The simplest format is a source file which just has one source name or position per line. Positions and names can be intermingled on different lines. E.g., a simple list might be

 Abell 1656
 10 14 12.9 -38 16 2.4
 10.737 +18.29
If you specify positions rather than target names, the coordinate system is assumed to be whatever is set in the Input Coordinate System option.
When you upload a source list the table created will have a text column with the original input and columns corresponding to the J2000 positions (or null if no position could be determined for a given row). We created a list of 109 positions by just querying for the position of the Messier objects (You can do this in Xamin by querying the Messier catalog). To upload the list we click on the Session/Upload menu. This was one of the options that was grayed out before we logged in.

When we start the upload, we got a file upload pane. We specified a table name we for how we want to save the table, and specify the file we are going to upload. Xamin will look at the file and determine the file type automatically.

file upload

After the file is uploaded we got a notification that the upload was successful.

file upload notification

The uploaded table is now available for queries just like all of the native tables. A tree of User tables is available up in the Table Explorer (marked 1 in the figure below) and or we can enter the name directly (but remember to include your user name as a prefix for the table name).

Now that our table is uploaded, we're ready to do the anticorrelation. In the examples we've switched to log into the test user account. That's available to you to play with (the password is also test) but you can't add or delete tables from that account, so uploads won't work there. However it already has a copy of the messier catalog as a user table.

We click on the User tables (1) to open them up. Then select our new table (2). Next we add XMMMaster to the correlation. We just entered it in the direct entry box (3), but you can choose one of the other methods. With both tables selected (4), we selected the Correlation options and indicted that we wanted an anticorrelation(5).

setting anticorrelation

We also decide that we'd prefer to set the cross-correlation offset allowed. We open the Parameters explorer (1), and replace the Dft in the automatically generated correlation constraint with an explicit numerical value in arcminutes. We chose 30 (2). We're doing an anticorrelation, so that means we're asking for all of the rows in our uploaded table for which there is no XMM observation within 30'.

Finally run the query by clicking on Query to ... Correlate (3). We find all of the rows in our list that haven't yet been observed by XMM (4). By scrolling to the bottom of the result we see that almost half, 44, of the Messier objects have never been observed by XMM. You might see a number that's a little less if you try this if XMM happens to have observed a few more since this figure was made.

messier/xmm anticorrelation result

Let me know whenever there is a new observation by Chandra of a target in my list.

Xamin has a very general facility for telling you whenever a query result changes. First you need to save the query result as a user table. Just set up the query and then Query to... Save. You can only save results if you've logged into Xamin. In Session/User tables-info you can see a list of all of the tables you've saved or uploaded. When you save a table, you get an option to see if the table would be different if we re-ran the query that created it. You can check daily, weekly or monthly. When a change is found an E-mail will be sent to you showing the differences. You can also check manually any time you log into the system.

We'll start with the same source table we uploaded in the last example. We want to be notified whenever there is a change of status of a Chandra observation near these sources (including new observations). Basically that's just a correlation of chanmaster with our uploaded table. We know how to do that. First we set up the tables and the correlation. We're doing a regular correlation this time, not an anticorrelation: we want to find all of the new data on any source in our list. So we need to make sure that the anticorrelation flag is not set. We don't really need all the Chanmaster fields, just the target info and the archive status will do. So we limit the information that's output in the parameters explorer.

chandra/mylist correlation

We can run this query easily enough and see that there over 700 Chandra observations near Messier objects already. We want to know when there are more or when the status of one of the existing ones changes (e.g., when the data is archived).

The first step is to save the results of this query as a user table. We just click on Query to... Save. This causes a window to pop up asking us for the name we want to save the table as, similar to what we had with the upload (but we don't need to specify the source file).

saving a query
After we give it the table name the query runs, but no output is displayed. We just get a confirmation that the table has been saved.

Our saved table is now ready to be queried itself or perhaps correlated against another table. To see all of the tables that you have available in your account you can click on the Session/User tables-Info option (1) This brings up a pane that lists all of the tables in your account (see below). There's also a list of saved query states, but we won't discuss those here. You can use this window to manage your tables, deleting obsolete ones with the icon.

However, what we're interested in is the Offline Checks? column for the tables. We find our saved table (2) and click on the the Never value set there (3). This brings up another form that allows us to request that Xamin check periodically for changes. We can specify the frequency (4) with which to do the checks, and also what is to happen if a change is detected (5).
setting up a query check

The default action when a change is detected is to send E-mail and update the table. The next time the check runs it will only find further changes, not re-notify you about the older changes. You can ask only to be informed of changes leaving your saved the table alone. That doesn't mean that you're doomed to getting continual notifications: no check is run if there hasn't been a change to one of the participating tables since the last check. You can also ask that the table be updated without notifying you. Perhaps you want a table of the 100 longest Chandra exposures and you'd like to have it updated automatically as new observations come on-line.

Make your choices and click on the Update button. You can reset your choices anytime.
If you want to do a manual check to see whether something has changed, you can click on the Changed? link for the table. That immediately reruns the query that generated the saved table and displays any differences.
Note that you can't check for changes in uploaded tables -- although you can (we did!) use an uploaded table in a correlation query you save and then check. Uploaded tables are something that's maintained by you not by the server. It only changes if you change it.

What if I only want to see Quicklook data products and abstracts for ROSAT?

Select the rosmaster table from the Master observation tables list and specify any other criteria (position, time, radius, etc) that interests you. Run the Table query using the Grid table with products output option (it is the default format). When the results grid appears
  1. Click the Edit Data Products button to display a pane showing the hierarchy of data products for the rosmaster table.
  2. Expand product nodes and select/deselect items until only the Quicklook data and ROSAT Proposal Abstract are selected
  3. Click the Apply button.

filtering data products

The current grid will redisplayed with only the selected data products shown (4, see figure below). This setting will apply to all future rosmaster results. After the new results are displayed a Product Limits pulldown menu will appear at the top of the Window (5). Entries will be added to this menu for tables that have had their products filtered. To change or reset data product selections find and click the table name in this menu or click the Limit Data Products button in the table results grid.

filtering data products

How do I select only certain image files for download?

The types of data products downloaded can be limited by using a string that contains the Unix shell wild-card * in the File Name Filter for Download box (1). The filter is applied to the full path name. Enter *.gif*;*.jp*g* to download only GIF and JPG files. The ; is used to separate the filters and is treated like a boolean OR. Click the Download as Tar File (2) and the filter will be applied as files are collected for the tar file.

filtering data products

How do I create a script of Unix shell commands that will allow me to download individual product files?

The Wget Commands (1) and Curl commands tabs provide the shell commands to download each of the data products listed in the Products tab. Commands can be striped, copied and pasted to create a script or they can be downloaded to a local file by clicking the Download As File button. Any filter that has been entered in the File Name Filter for Download box (3) will be applied as the commands are downloaded.

Wget and curl are included in most distributions of Unix/Linux. Information on wget can be found at the GNU Wget site and on curl at this Curl site.

creating shell commands

Customizing Xamin

Xamin allows you to build up queries and save them for future use. If you have an Xamin account, you can save a query and reuse it later in a current session or in future sessions. Just click on Session/Save Session and give the session a name. If you save a session with the name default, then this session can be automatically restored whenever you log in. The session state includes whatever menu options, times and positions, tables, and parameter constraints that you have set. You can save any number of sessions. You can restore a session using Session/Restore session or from the User Tables-Info window described above.

Reference Manual

The Xamin interface provides a powerful Web based GUI to query the HEASARC and other databases. Xamin uses a number of sub-windows that are rendered within a single browser window. To minimize confusion, these sub-windows are called panes in this document. The term window is reserved to mean a browser window. Depending upon the browser and user settings a browser window may be a full window or a tab panel in tabbed-browser window.

Many panes are persistent. They can be dismissed and recovered with the same state. Results panes, e.g., tables and plots are not saved and the database must be re-queried to regenerate them if you delete them. You can minimize or hide them if you want to get them out of the way. Table 2.1 summarizes the Xamin panes. Only the major interface panes are shown. Various prompts, errors and acknowledgements also use small popups but their meaning should be clear in context.

A set of Pane control buttons at the very top of the Xamin window is provided to help users manage the primary panes of the interface. When Xamin starts there are three buttons there which toggle the visibility of the Feedback, Query and Products Cart panes. If there is a Plot Control pane another button appears which toggles this visibility of that pane. If there are table, plot results or product selection panes, then menus appear which have entries that allow for toggling the visibility of each result individually and global hide, show and delete options.

Pane Initiated by... Purpose
Query Xamin startup Main window of the interface. Compose and initiate queries.
Table Query to ... Table Show table results. May show data products.
SkyView Preview Queries Show SkyViewpreview images
Plot control Query to ... Plot Specify plot parameters.
Plot Submit on Plot Control Pane Show plot results.
Products cart Product selection on Table pane Filter and download products.
Matching tables Keyword search in Tables Explorer Show tables matching keyword search.
User account Session menu/User tables-info Manage user account and tables.
Monitor tables User account pane Frequency column (for saved tables) Set schedule to monitor query result for changes.
Feedback Panes control Provide feedback and bug reports
Product selection Table pane/Edit products Select which product to retrieve for a table

This reference document describes each of the panes of the interface in turn.

The Query Pane

The query pane is the primary element with which the user will interact during their Xamin session. Here is where the user selects tables, defines constraints and initiates queries. The title of the query pane indicates the whether the user has logged onto an Xamin account or is not logged in and is just a member of the 'Public'. The remainder of the query pane is divided into sections stacked vertically which are described in turn below.

query pane

The Menu bar

The menu bar at the top of the query pane is used to manage user sessions and set options for user queries. The menu bar also provides a help menu with links to on-line documentation (including this document).

The Session Menu

The session menu is used to control the overall characteristics of your connection with the Xamin server. Most of the options in the session menu are unavailable until a user logs into Xamin.

The Options Menu

This menu affects the way each query is interpreted and the results are generated.
Input coordinates.
Select one of the radio buttons to set the coordinate system that will be used for coordinate strings input in a positional query or in a source list. This does not affect the results if target names are entered.
Name resolvers.
Check the name resolvers that you would like to be used in converting names to coordinates.
Output coordinates.
Specify the coordinate system to be used for the primary output positional fields in the query. This need not be the same as the selection made for input coordinates (though the default is to use the same coordinate system).
Controls how correlations are performed, including whether an anticorrelation is desired and whether data from all tables should be included.
Output Format.
Select the desired output format.
Show output in.
You can control where text outputs are displayed. Grid outputs are always displayed in a pane in the Xamin window, but you can control where text output goes. These buttons only have an effect when the output format is Aligned or Streaming text.
Default fields.
This submenu is used to select the defaults for fields that are to be displayed in the query. The Parameters Explorer can be used to get much more detailed control over the fields to be displayed, including definition of synthetic columns created by the user.
Select the products that you will show for the user. Products are visible only when using the grid output.
Query control.
Query info.

These options allow you to get information about the query. This is shown after the query text for text output. It can be viewed in the grid query by clicking on the ? tool.

Display theme.
This allow the user to change the overall appearance of the GUI.

The Help Menu

This menu allows you to get to several different help resources.

The Actions Area

This area comprises three sets of buttons to initiate queries and to clear areas of the query pane.

Find matches in...

These butttons are used to initiate Discovery queries. These query master tables that allow Xamin to search all tables or selected tables to find those that meet the specified position or time constraints. The result is a grid where each row represents a single table (including some table metadata), and gives the number of matches within that table. A link at the beginning of the table starts a query of the table.
All HEASARC tables
This option is available when the user has not specified any tables but has entered a position or time constraint. All HEASARC tables will be examined.
Selected tables
This option is enabled when the user has selected one or more tables and position or time constraints. The number of matches for each of the selected tables will be given. Non-HEASARC tables will be ignored.

Query to ...

These button initiate queries of one or more tables.
Query a single table with the specified position, time and/or parameter constraints. If no constraints are specified all rows of the table will be returned (subject to the current limit on number of rows). The result will be returned in a query pane for Grid or Text formats or will initiate a download dialog for other types.
If two to four tables have been specified the user can correlate the tables. Any position or time constraints are applied to the first table to which they can be applied. A positional cross-correlation constraint is normally supplied, but can be deleted or modified by the user. The result options are the same as for a table query.
Run a single table or correlation query but plot the results. A plot control window will be returned for a successful query.
Run a query and save the result in the user's personal area. This option is only available when a user is logged in. The user will be prompted for the name to be used for the table.

Clear ...

These four buttons are provided to clear/reset elements of the query form.
Deletes all entries from the selected tables tree. It does not reset the Available tables (e.g., if the user has opened a branch in that tree it remains open).
Remove all user specified constraints: user entered positions and times and any constraints the user may have added in the Parameters Explorer area. It does not remove the system generated cross-correlation constraint between tables when the user has specified a cross-correlation.
This resets all menu options to their default values.
Equivalent to doing all of the other three.

Standard Constraints

Users can enter centers and radii for searches as well as the any desired epoch for observations in these fields.

Positions and Radii

Positions may be specified in a variety of formats, target name, decimal degrees and a variety of sexagesimal formats. Radii may be specified using degrees, arcminutes or arcsecond units. The unit may be specified in the radius string by appending the chracter d (or D), ' and " respectively. This overrides the radio button selection of units. The initial default for radius units is arcminutes.

Multiple positions may be included in the position box separated by semicolons.


Times may be entered in ISO format (YYYY-MM-DDTHH:MM:SS.ffff), Julian days or Modified Julian days. The format of the date is automatically parsed to make the selection. Many variations on the ISO format are permitted. As users enter times, a red boundary indicates that the format of the data is not recognized. Fields for both start and stop times are available. It is an error to specify a stop time without a start time, but specifying a start time alone is allowed and represents an instant in time.

When making queries of tables that have only a single time specified, Xamin normally looks within 0.5 days of the specified time for each row in the table.

The Tables Explorer

This region is used to discover and select the tables that are available in Xamin. There are three main ways to enter table data. Users can enter table names directly, they can use the one of several trees to select tables, or they can search for tables that match keyword criteria.

What tables are in Xamin?

Xamin allows users to select from from four different sources of tables: HEASARC tables, VizieR tables, tables accessed through VO protocols, and user tables. In principle tables from all sources can be matched and correlated, but users should be cautious when attempting correlations with external tables since these may not be feasible if they require downloading and ingesting very large external tables. E.g., one can in principle correlate with the USNO B catalog at Vizier (table I/284), but if one tries this without specifying a position, then program will try (and fail) to download the entire USNO B to a temporary table within the local database to do the correlation.
HEASARC tables
The HEASARC provides direct support for over 600 tables. With a few exceptions tables are entirely independent, i.e., no special correlations are anticipated with other tables. Many of the most popular tables index tables from high energy or microwave missions. These tables often provide links to archival data products which the user can select, add to a products cart and download in a variety of fashions. Most other tables are object catalogs, which describe the characteristics of objects in the sky. Occasionally these will have data products as well.

HEASARC tables may be entered directly. When typing in user names possible completions will be shown and may be selected. HEASARC tables are available through a variety of table hierarchies (alphabetical, by mission, by regime, and by object type). The keyword search will find HEASARC tables whose metadata matches the search terms.

Documentation on a HEASARC table can be displayed in the Information area by clicking on the table name.

VizieR tables
VizieR tables are available in the in the Tables Explorer hierarchies under External/Vizier. Over 20,000 distinct tables may be queried. Vizier tables are grouped into resources which are in turn grouped into either broad categories (given by Roman numerals) of tables where the name is the Roman numeral followed by an identifying numeber (e.g., I/284 is the USNO B catalog), or by a journal abbreviation followed by the volume and page of the article in which the table was published, e.g., J/ApJ/597/204. A resource may contain either a single table or multiple tables. If there are multiple tables in a resource, then a table identifier follows the resource, e.g., I/100A/w50 labels table w50 in the resource I/100A. Often tables within a resource are expected to be joined in some fashion using ID's specific to the resource.

You find Vizier tables in the table tree under External/Vizier. You can enter table names directly, or you can use the metadata query to match against Vizier tables. Vizier tables will not be returned in discovery queries.

Many Vizier tables do not have positional columns. Vizier tables support field selection, sorting and simple constraints natively. More complex queries may require the Vizier data to be downloaded into a temporary local table where the complex constraints can be addressed. No data products are associated with Vizier tables.

Documentation for Vizier tables can be displayed in the Information area by clicking on a table or resource name.

Virtual Observatory Tables
You can access data through several VO protocols using Xamin. The Table Access Protocol provides access through services that provide relatively sophisiticated local queries. Most constraints on a table can be handled natively. Image and Spectral data may be accessed using more specialized protocols. These only support positional constraints natively. All other constraints are implemented by downloading the results and filtering the temporary table.

Image and spectral services generally provide a link to a single product for each row in the returned results. Since this is a link and not an archive file they cannot be added to the download cart.

VO resources can only be accessed through the table tree in the External/Queryable tables, External/Image services and External/Spectral services entries. These link to services the user the VO Table, Simple Image, and Simple Spectral Access protocols respectively.

No documentation is avaiable for VO tables other than the row documentation available in the Parameters explorer.

User tables
User tables are appended at the end of the table tree. User tables are created either by uploading a table or saving a query result. User tables are only available after logging into a user account. User tables may be specified by either entering the full table name (in the form user.table) directory or by selecting them under the User entry in the the table tree.

No documentation is avaiable for user tables other than the row documentation available in the Parameters explorer.

Entering tables directly

The tables entry box allows the user to type the table in directly. It also allows selection from a menu which shows all matching HEASARC tables. Note that non-HEASARC tables can be entered, they just are not included in the menu suggestions.

The available tables tree

The available tables tree shows tables available for querying in a number of hierarchies, including alphabetical, mission, regime and object type. Only HEASARC tables are shown in these hierarchies. An External tree shows known external tables. If the user has logged in and has uploaded or saved tables, these tables will be shown in the User tree. Trees may be opened or closed and either leaf nodes -- tables -- or entire branchs may be selected by clicking on the Add icon or double-clicking on the node, or dragging the name of the node into the selected tables are.

Table Keyword Search

The table keyword search does a text search of the documentation for HEASARC tables and indexed external tables. The text search handles grammatical transformations (e.g., singulars and plurals) and attempts to grade each match to show the best matches to the users input. The results are shown in a pane with the table name and title and brief extracts of the matching text. Note that the table metadata is included in the text search so that occasionally the apparent matches may includes somewhat jumbled text.

The selected tables tree

Regardless of how users select them, selected tables are shown in a separate tree. Users can delete tables by using the delete icon () or double clicking on th etable. The entire set of selected tables can be cleared using the Clear...Tables0 or Clear...All buttons. If the user selected a sub-tree of tables, then the entire subtree will be shown in the selected tables tree, including the branch nodes. The entire subtree may be deleted by deleting the parent node. E.g., you could select all of the Observation master tables by clicking on the Add icon in the available tables tree. A 'Master observation tables' node will be added to the selected tables tree. Deleting that node will deleting all of the contained tables.

If no tables are selected the user may make discovery queries which search all HEASARC tables.

If exactly one table is selected, queries will be made of that table. The user may specify positional, temporal or parameter constraints in the query (using the additional constraints area).

If 2-4 tables have been selected then the user may do either discovery queries looking for the number of matches for the specified positions and/or times, or they may do a correlation of the selected tables. The Options/Correlations/Correlate Tables menu items controls which is performed. When correlation parameter constraints can be levied against any and all of the tables involved in the correlation. If the Options/Correlate/Anticorrelate flag is set, then the correlation is an anticorrelation against the last table selected. E.g., if the selected tables are ROSMASTER, ASCAMASTER and CHANMASTER, then the result includes the correlation of ROSMASTER and ASCAMASTER where no corresponding Chandra observation is found.

If more than 4 tables have been selected then only discovery queries are supported. [Generally correlations get very slow when many tables are involved.] Note that user and external tables are not currently 'discoverable' so that you cannot determine the number of matches against them using a discovery query. When doing a discovery query they are ignored. Only the number of matches against the specified HEASARC tables will be returned.

External tables

Xamin attempts to treat external tables as if they were local. If the user requests operations (constraints that cannot be met by the remote system, correlations), then there may be an operation downloading the external table into the local system whence query can proceed. As much of the query as can be accomplished remotely will be delegated to the remote system. However it is not difficult to submit queries which would involve downloading millions of rows of the external tables. Such queries are unlikely to be successful.

The Parameters Explorer

Use the parameters explorer area to see the fields available for the selected table (or tables), add any constraints other than the standard position and time, and specify the output fields Users can also add dynamically computed columns and specify the sort order for the query.

The parameters explorer is only available for single table queries or for correlations. It is reset every time you change the selected table or tables. To open the Parameters Explorer simply click on the its title bar. The Parameters Explorer and Tables Explorer share the same space. Only one can be open at a time.

Table fields

Most of the explorer is taken up by a grid showing the fields of the input tables. The name and description of the field are generally visible by default along with an area in which users can enter a constraint on the field. Multiple constraints may be entered on a single field if they are separated by semicolons (;). These constraints will be ORed in building the query. Simple constraints of text fields will normally have implicit quotes placed around the string values but the user may disable this option in the Options/Query control menu.

In a text comparisons a '*' may be used as a wildcard match along with the SQL standard '%'. Text comparisons are generally not case sensitive. A case sensitive comparison may be made in a table by specifying it using an generic constraint unassociated with a particular field.

Users can click on any of the headers to bring up a menu to control which fields will be displayed. In addition to the defaults, the table name, minimum and maximum for each each field are available.

The display divider

The red row in the fields grid is used to separate the fields to be displayed from those which are to be hidden. This can be dragged up or down to change the displayed fields. Other fields can be dragged across it to change their visibility. Users can select and drag multiple fields at a time.

Adding new fields and constraints

The User-defined column button allows the user to specify a new field to be included in the output. Any name may be given for the field. The content of the field is given as any legal SQL expression. This may include one or more fields in the table and may include any SQL functions supported by the database.

The Generic Constraint button allows the user to specify a logical SQL expression which must be satisfied for a row to be included in the output. Since these constraints are not associated with specific fields in the table any constraint strings must be delimited by single quotes. A string comparison will normally be case sensitive unless the user explicitly addresses case in the expression (e.g., by using the upper() function on both sides of an = operator).


Users may specify the sort order for the results using the Sort combobox. Users are prompted with the names of the fields in the table, but sorting may be done on any expression. If multiple sort fields are requested, these may be specified with the names separated by commas. E.g, expr1[:-],expr2[:-] where the default direction for each field is ascending. A :- is appended to make it descending.

Aggregate operations and groups

The Xamin interface supports aggregate functions, one of the more advanced features of SQL, in a straightforward way. Suppose you want to know the total exposure for each Chandra target. We put the target name and a new synthetic column with the expression sum(exposure) as the only two fields we are going to output. Xamin notes your use of an aggregate function in the new column and groups the output by any parameters which are not aggregate functions. So you get one row output for each distinct target name. The aggregate functions available include count, sum, stddev, variance, min and max. Rows where the argument of the aggregate function would be null are omitted from the query.

The Information Area

Note: As of version 1.7 the Information Area has been moved into a separate resizable pane. This makes it much easier to display table documentation from multiple tables.

This area is used to display information about tables or classes of tables. If the user clicks on a table entry in either of the table trees or in the keyword search pane, the documentation for that table is shown. If the user clicks on a branch node of a tree, then the information shown depends on the node. Typically if these is a penultimate node, i.e., its children are tables, then a summary listing of the contents will be shown. Tables can be selected from this listing by clicking on the Add icon.

Table Results

A new table results pane is shown for successful queries. The title bar includes the source table (or tables) and may give further information about the query. The bottom of the query box includes fields that may be used to reissue the query changing like the maximum number of rows, or the output format. At the top right of the query box are several query widgets. These allow the user to shrink the query pane to a narrow bar (click on the bar to re-expand it), to restore the query pane to the settings used for this query, to print the query results and to get further information about the query. There rightmost X widget destroys the results pane.

Query example

Grid results

Grid results are shown in a flexible output format. Users can resort the data by clicking column headers on the top row. Column headers can also be dragged to reorder the columns. If you click on the column header a small menu is shown which allows you to select which columns are to be shown. Grid results may also include data products.

For most grids, mousing over the column headers will show the descriptions given for the columns in the documentation of the associated table. Similarly mousing over the row number at the beginning of each row will show all of the fields associated with that row. This is displayed in a persistent pane that the user must explicitly dismiss.

Text results

Text results are shown in a simple pane with no special formatting. Text results can be striped and render much faster than grid results. Text results do not show data products.

Discovery results

When doing discovery queries the user gets back one row for each table that matches the specified position or time criteria. A table icon at the beginning of the row can be used to initiate a query of that table.


Products are available when grid output (the initial default) is used. If data products exist for any row there will be an expansion icon in the second column. This icon (1) can be clicked to reveal the top level of data products for that row. Sub products can be retrieved and displayed by clicking the expansion arrow icons (2).

The data product selection buttons in the results pane allow users to select data products for particular rows or the entire result. If users have expanded a products tree they can select products individually by clicking on the shopping cart icon before a product. Users can directly go to the URL associated with a product by clicking on the product name. After products are transferred to the shopping cart, users can download products using its capabilities.

SkyView Previews

When a user makes a query for a single position (which may include other criteria), preview images are generated by query SkyView for that position. The initial previews generate 100x100 pixel images in the default resolution of the surveys. These default to the DSS optical survey with 1.7" pixels and the ROSAT All-Sky Survey (RASS) with 0.0125 degree pixels. Users can resize previews to get smaller or larger images. The resized images will be used until the user either deletes the preview panes, or changes the surveys selected, which will automatically delete the panes.

The Shopping Cart

The shopping cart pane is used to control the actual download of data to the users machine. Users can send products to the shopping carts throughout an Xamin session and download data whenever they wish. Products are transferred into the cart from table panes when users request all data products associated with particular rows, or individual data products.

shopping cart pane

The products cart has three tabs. The products tab provides a listing of the data products where users can delete products (or jump to them as URLs). This is the only tab in which products may be deleted. Users can delete all products, or just those that have been highlighted (by clicking on them) using the appropriate buttons.

The WGET and CURL tabs allow the user to download scripts that they can run on their machine to access data, but do not allow a user to delete selected products.

Filtering Data Products

For all download options a filter using the Unix shell wild-card expressions (e.g., *) can be applied to limit the files that are downloaded. Enter a filter string in the File Name Filter for Download text area. The filter is applied to the full path name. For example, the filter */bat/*.hk* would limit data products to those that are under the directory bat and contain '.hk' in a subdirectory or file name. A file such as /FTP/swift/data/obs/2005_04/00035014004/bat/hk/ would be included. Multiple contraints separated by a semicolon (;) will be treated as boolean OR. So, *fits*;*gif* will result in products with names containing 'fits' or 'gif'. If the filter results in no files being found the downloaded tar or script file will indicate this result.

Finding WGET and CURL

The network utilities wget or curl are included with most systems. To download wget or get more information visit the GNU website.

Plot Control

The options for plotting are sufficiently complex that a separate Xamin Plot guide is provided to describe how to do plotting. The plot control pane allows the user to select among histograms, 2-d and 3-d plots, set the axes for the plots and myriad of axes and plot parameters. Users can also plot multiple samples within the plot. Use the Sumbit button on the plot control pane to generate a plot.

Plot control

Plot Results

Plot results panes simply enclose a GIF or other format image. They have no internal functionality although they have widgets simple to the query table result panes.

Plot example

User Accounts Pane

The user account pane is shown when a user logs in or using Session/User Tables--Info menu entry. This pane shows the saved user tables and query configurations.

User tables

The title bar of the pane shows the user's name, and the amount of space used in the Xamin system. Currently no quota's are enforced but this is likely to change in the future. Two grids display the tables the user has saved and the saved query configurations. A Manage Account button provides a shortcut to the Login window where the user can update their account parameters, or delete the entire account.

Saved Tables

Users can save tables either by uploading them (Session/Upload), or using the Query to...Save option to run a query. Saved tables can be used just like system tables in any query or correlation. Two saved tables can be correlated against one another. This delete icon () can be used to delete a saved table. For non-uploaded tables users can click on the entry in the 'Offline checks?' column to ask that the system reissue the query and see if it returns the same results. If not then the user can request that they be mailed a notice of the changes, have the table updated or both (the default). The 'Changed' link at the end of the row allows the user to check immediately whether the results have changed, but only a simple summary will be given.

If the user specifies a table that already exists when upload or saving a table, then the results of the upload or query will be appended to the existing table so long as the query fields are compatible. Otherwise the query will fail.

Saved Query Configurations

Queries can involve complex setup which users may wish to repeat with slight changes. A query configuration can be saved using the Session/Save Session menu. Click on the Apply link to restore the session. Saved configurations can be deleted by clicking on the delete icon ().

If you name a session 'Default', then that session will be automatically restored when you log in.

A single session can be saved to an browser cookie even without an account.


A feedback pane is integrated in Xamin as the very first button on the page in the extreme top right of the pane. Users can send bug reports, suggestions or comments. Only the title and summary fields are required, everything else is optional. The system automatically appends a copy of the state of the system at the time of the request which may help in tracking down bugs.


Product Explorer

Product explorer panes allow users to see and select the kinds of products associated with particular tables. A given table may have a whole hierarchy of data products associated with it. If a user wishes to retrieve all data products associated with the table, they can just download everything, but the product explorer panes allow users to select only subsets of the products for subsequent requests.

A product explorer pane is created when users select the Edit Products button in grid table result.

product explorer A product explorer pane is associated with a specific table or correlation. Users can select the products they wish to extract from tree of avialable products. The product selections may be applied to the current query if the product node was made visible by clicking on edit products for a specific query and regardless they will become the selection for future queries of the associated table.

Pane Management

Xamin can produce many panes within its window and to help users manage these, a set of buttons is provided at the very top line of the window. There can be up to seven buttons shown here. The first three are always visible and they toggle the visibility of the feeback, query and product cart panes respectively. These three panes cannot be deleted. Clicking on the X widget in the top right corner just hides them.

If a plot control pane is available, then a fourth button toggles its visibility. However plot control panes may be deleted. There is never more than one plot control pane which is associated with the last plot request.

There may be many table, plot and products selection panes. If there are any table results present, then a select box with the name 'Queries' shows. It will have the options 'Show All' , 'Hide All' and 'Delete All' which will show, hide or delete all of the table results. These three entries will be followed by a single entry for each pane. Clicking on this entry will toggle the visibility of the specified pane. When a pane is shown, it is also moved to the top of the viewing stack.

Similar select boxes with the name 'Plots' and 'Edit products' will be shown whenever any plots or product explorer panes are available.

Users can collapse most panes by clicking on the - widget at the top right of the pane. This collapses the pane to just its title bar. The collapse widget changes from a - to a +. To restore the pane, just click on that.

Panes can be dragged anywhere in the browser window. Clicking on a pane title bar will normally move it to the top of the pane stack.

The Single Box Interface

Xamin provides support for initiating queries using a single input box. The single box interface is intended to be plugged into other pages to provide a low profile interface to the HEASARC archive. An annotated version of the single box interface is available. However the only required element for an implementation is one text entry box. When a user initiates a query from this interface the inputs are analyzed and an Xamin session is started.

Single Box Inputs

The single box interface parses the users inputs into blank separated tokens and uses a set of heuristics to decide what each token means. Supported token types include:
Token types
Type Description Example[s] Heuristic
Positions Numeric positions in sexagesimal or decimal format, multiple positions can be specified. 10 10 10, 20 20 20.3
Token sequences that match sexagesimal format or pairs of numbers that have magnitudes < 1000
Target namesNames of targets that can be resolved into positions. If names or positions include spaces they should be enclosed in quotes though sometimes such names can be recognized without quoting. 'eta carina'
'3c 273'
Tokens not otherwise identified are checked using a name resolver. Tokens that are not targets are treated as keywords.
Radius The radius for cone searches.10'
A valid number followed immediately by ', " or d
Times Times may be specified in JD, MJD or ISO formats. Time ranges may be given. 1990-10-10T14:15
String matching ISO time formats. Positive numbers > 10000 are treated as MJD times, (or JD if > 1000000)
Coordinate systems The coordinate system used for input and output J2000, Galactic, B1950, E2000 Case insensitive keyword match
Table names HEASARC and Vizier table names rosmaster
Exact match for HEASARC tables, tokens including "/" are assumed to be Vizier tables.
FormatsThe format for the output of a table query or correlation Text, Excel, FITS, VOTableCase-insensitive keyword match
Missions Mission names. These are largely treated as keywords but may be converted to standard form. Multiple missions may be specified as M1|M2|M3 ROSAT
Case insensitive match
Metadata Keywords Look for tables that have these keywords in their metadata or description. Only tables that match all keywords will be used. dwarf novae
clusters of galaxies
Any token that is not otherwised matched which does not seem to be part of a target name is assumed to be a keyword.
ConstraintsConstraints on the query. If a literal string value is used it must be enclosed in single quotes. exposure>10
Tokens containing <,> or = are assumed to be constraints.

How are the tokens used?

Target names, coordinates, time and radius constraints are used to fill in the standard constraints in the Xamin query form. The output format and coordinate system tokens are used to set the appropraite options. If a small number of tables (currently between one and four) have been specified then the query is assumed to be a correlation and any specified explicit constraints are added. If no tables or a large number of tables are specified, then a discovery query for the given positional and time constraints is initiated and any explict constraints are ignored.

If no tables are specified, but there are keywords, then tables matching those keywords are found and if there are position/temporal constraints a discovery query on the tables matching the keywords is done.

Users are left in an Xamin session using thssh ase standard web interface. Depending upon their inputs they may find themselves with a set of tables matching their keywords, a discovery query result, a single table query or a correlation. They can extend or correct the actions that were taken and do further analysis.