The Xamin Web Interface

The Xamin web interface is being updated. The update is largely cosmetic, relocating and renaming buttons to make its use more intuitive. We are continuing to update this document.

If you find videos helpful, here are a few of somebody using Xamin to show you some of the workflows:

The rest of this document goes into more detail to describe how to use the full Xamin web interface. The following sections comprise a comprehensive reference manual which discusses each element of the web interface.

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.

Xamin quickstart use cases / workflows

A few common workflows described briefly:

• You have a simple question asking for data matching positional or temporal constraints only.
  1. You can enter them in the Xamin Quick-Search interface at the top left, e.g, "swiftmastr, cen a, 2010-01-01..2020-12-31" and hit return.
  2. The corresponding rows of the catalog will show up in the Results pane. Note that the default search is limited to 100 rows and a default set of columns so that you can preview them before sending a long query. You can resend the query to ask for the full results using the "Query Modifier Bar" at the bottom of the results table.
  3. In the Results pane, just to the top left of the table, you can "Click to filter by product type". This opens up a window to brows the hierarchical definitions of data products so that you can check and uncheck those that you're interested in. When you have made your selections, you can dismiss the window.
  4. You can then click in the top right of the Results table to add the products to your 'cart', i.e., the list of data products you will want to download. You can add them either for "Highlighted rows" or "All rows". Xamin will go look on disk for those matching the types you selected (which may or may not exist for all observations).
  5. At the bottom is your data products cart, where you can choose to have a tar file generated for download, or use a script of wget or curl commands, etc.
• You have a position or source you're interested in and want to find out what data are available for it. Follow these steps:
  1. Enter the source name or coordinates in the target constraint box. If you hit return, the viewer should recenter on those coordinates.
  2. Or use the Aladin viewer's own tools to navigate to the region of interest, and shift-click to sent the constraint region for Xamin to match. A circle representing the search region will appear, while its coordinates and radius will appear in the constraints box.
  3. Under the constraints box, click "Search" for tables matching the constraints.
  4. The tool will do a quick search of all holdings and present the summary of results in the Matches in HEASARC Catalogs pane. Each row tells you that a given catalog has so many matches.
  5. Click on a row of the Matches table to send the query to fetch the full results of the constrained search on that catalog.
  6. Then you can continue as above.
• You want to locate all available Chandra observations for a list of sources you are interested in:
  1. In the constraints box, click "Select file to upload" and give it your list of sources, e.g., in CSV format.
  2. In the "Tables to search" box, you can start typing "chanm" for Chandra's master observation catalog and hit return.
  3. Notice that at the top, the Current selections will show your uploaded table and chanmaster. If you click to open the Parameters Explorer under the Tables browser, you can customize the cross match. By default, it shows "||a,b||
  4. It is ready to cross correlate when you hit the "Send query" button at the top right.
  5. Under Results, you should now see the cross-match results, i.e., a list of all Chandra observations for the list of sources you specified.
• You want to search all of the master catalogs for observations of your source:
  1. Enter the location or name of your source as above.
  2. Open the "Available Tables" pane.
  3. Click the green plus next to "Master Observation Tables". This will add all of them to the "Selected tables" list.
  4. Under the search constraints box, click the "Search" for tables matching button. This will do a quick search of each of the selected tables as in the second use case above. You can then click on each row to send the full query for each table.
• Notes:
  • Currently, there is not a button to send multiple full queries in one click. You can do a quick-search of multiple catalogs but will then need to click on each match to send the full query. If you need the ability to send more queries than you can click individually, we suggest you look at the Xamin CLI Guide in order to learn how to script the queries.
  • Note also that if two to four tables are selected, the "Send query" button in the top right is enabled but may not be doing what you think. The default behavior is to do a positional cross-match between the selected catalogs when more than one are selected. See below for more about cross-matching.

Overview of interface

The Xamin interface provides a powerful Web based GUI to query the HEASARC and other databases. There are a variety of different workflows that can be performed with Xamin, and frequently the same result can be obtained in several different ways. Note that when the page is first loaded, there are a number of sections, called panes, that are minimized at the bottom when not in use. When results are returned, the focus is scrolled to the relevant opened pane. There is a top menu bar that is fixed regardless of how far down you scroll, so that you can always access its functions. In between is the main area where you enter constraints and visualize the region of the sky that you are searching.

Table 2.1 summarizes the main components of Xamin.

Component	Purpose
Quick search	Here you can enter more straightforward queries on a single line, such as "chandra 'cen x-3' 2000-01-01..2010-01-01" and hit return. See the linked page of examples. Note that using this box will clear the current selections.
Constraints box	A variety of constraints can be specified here: Positional constraints can be given via a target name (which will be sent to a name resolver and converted into coordinates) or coordinates. (To change the default coordinate system from J2000, use the Options menu at the top right.) See below for uploading a list of targets. Temporal constraints can be given in several different date formats (yyy-mm-dd[Thhmmss] or decimal MJD, with two dots between for a range, e.g., "2010-01-01..2010-12-31") that will be recognized automatically. If you are looking for data associated with a publication, you can simply enter its ADS bibcode and nothing else. If no constraints are specified, then you can skip to the box below to select a table to view its unconstrained contents. Alternatively, if you have entered constraints and would like to see what matches there are among all HEASARC tables, the Search button below the constraints box will do a preliminary search simply to count matches. See the Matches section below.
Tables search	You can specify the tables you are interested in by typing the name directly hitting return when auto-complete matches what you want. If you don't know its name, you can search by keyword, e.g., "chandra", to pop up a window that will allow you to select among tables that match your search term. When you have selected a table, it will show up at the top menu as a selection and apply to your subsequent searches until you deselect it. When you have a table selected, you can click the Submit query button at the top right, which will apply the constraints if any and return the results below in the Results pane. If you have selected multiple tables (see notes below), you can do a preliminary search with the button just above to "Search" for matches, which now will do a quick search to count the matches in the multiple selected tables instead of all HEASARC tables.
Viewer	The Viewer is based on the Aladin sky visualization tool. In addition to displaying a background image of the sky, you can use it to pan, zoom, search, and shift-click to select the region to query. When you have results of a query, the viewer will overplot the catalog points and link them (via highlight color) to rows in the results table.
Matches in HEASARC Catalogs	If you don't have a specific catalog in mind but want to find catalogs that contain matches to your constraints, you click the Search button between the constraints and tables boxes. This sends a quick search to the database merely to count matches to your constraints in each catalog. The results show up in the Matches pane below, and if you click on a given row, it will send the full query to that specific catalog and return the full set in the Results pane. The default is to quick search all HEASARC tables with positional and temporal information. If you have browsed and selected multiple tables manually, it will search only those.
Available Tables	You can brows the available tables in this pane. They are grouped in various ways such as by mission and alphabetically. Note also that under "External" you can find catalogs held by other data centers, including Vizier and those that are available for search through Virtual Observatory (VO) protocols. See also our NAVO web pages. At the bottom of this pane is a minimized Parameters Explorer discussed below.
Results	The results pane displays the rows of the specified catalog that match your search constraints. Further actions you can take with this window include: Note that by default the first search is limited to 100 rows and a default set of columns. You can re-send the query asking for more complete results using the Query Modifier Bar at the bottom of the window. If there is a plus symbol on the left side of each row, you can use it to browse data products associated with it. This generally applies to observation catalogs such as swiftmastr. More generally, at the top left above the results you can "Click to filter by product type" to check and uncheck product types that you are interested in for all rows. When you have selected the products you are interested (or all of them by default), you can add them to your cart using the buttons on the top right. You can select individual rows or add them all. They will show up in your product cart pane; see below.
Data products cart	Once you have selected the data products that you are interested in, whether they are entire directories or individual files, they show up in the cart at the bottom. Here you will find options for downloading them, such as in a tar file or by using an auto-generated script of wget commands. Note that here you can also further refine your selections based on a file name filter, e.g., "*foo*bar.gz" to further restrict the list of files retrieved.
Parameters Explorer	To perform more advanced searches with constraints on the columns in the table, you can open the Availables Table pane, select the table of interest, and then open at the bottom the Parameters Explorer for that table. This will show the columns that are available, where you can add simple constraints (e.g., ">1000") or more complicated constraints using the options at the bottom right. You can add a computed column and you can specify generic constraint expressions that may involve more than one column. These will be applied when you then hit the Submit query at the top right.

Further options

• Multiple-table queries are done through the two step process described above of searching for matches in a set of tables and then clicking each to send the full query. The default behavior of the "Send query" button, by contrast, if more than one table is selected is to attempt to do a positional cross-match between the tables (see below).
• Table uploads are a way to query a whole list of sources in one go. You can input your list in several formats such as CSV. Your list can contain only targets, in which case each target could be a name to be sent to the name resolver or coordinates to be parsed. But your table could also be targets and additional columns of information about them that you will use in a complex query. After you have uploaded your table, you can open the Available Tables pane and will see that your upload is selected. Open the Parameters Explorer below that to see the different columns. You can then use this to cross-match against one of our catalogs.
• Cross-matching is when you ask the server to compare two tables and return a constrained set of results based on both of them. Most commonly, this is done based on position, i.e., you specify that the coordinates in catalog A must be within a certain radius of the coordinates in catalog B, and if so, those two rows are combined and returned in the result. A simple application is to upload a list of N sources and cross-match against one of the master observation catalogs, e.g., swiftmastr. The result will be a table containing all of the rows of swiftmaster corresponding to each of your N sources. E.g., if the first source in your list was observed 7 times, then there will be 7 corresponding rows in the result. If you simply specify two catalogs without using the Parameters Explorer to define the cross match, then the default positional cross-match will be performed. Alternatively, you can open the Parameters Explorer to define it yourself.
• Debugging complicated queries can be difficult. One way to obtain more information is to look at the raw SQL that is sent to the database. Under the Options menu at the top right, you can select Query Info -> Show generated SQL and resubmit your query. In the new Results pane, you can click on the question mark at the top right to see how it interpreted what you specified. Be aware that this is sometimes quite long, as Xamin will, among other tricks, speed up queries by reformulating positional constraints. But if you can read SQL, this may be useful.
• Customizing the Xamin interface can be done with the Options menu at the top right. Here you can change the default coordinate system displayed, the default additional products to offer, the maximum number of rows, etc. If you create an account and log in under Session, you can save these settings for your future sessions.
• Plotting the data from a table of results is a function from the original version of Xamin that has not yet been ported to the new interface. But it will come back.

For more information on how to use Xamin, clarifications, feature requests, bug reports, help, etc., please use the HEASARC feedback page.