The Xamin Web Interface
This document describes how to use the Xamin web interface. The tutorial
illustrates Xamin in a series of videos.
The following sections comprise a
comprehensive reference manual which discusses each element of the web
Additional information on Xamin is available in other documents.
Additionalhow-to videos of the web interface are available from 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
Xamin, the Xamin System Guide can
An Xamin Video Tutorial
This section uses a sequence of videos to illustrate increasingly complex
uses of Xamin. These videos are not exhaustive guides to a topic, but show
how a user might interact with the system in practice. If you view these
you should have a good feel for most of the key capabilities of the Xamin interfaces.
The first thing you might want to know when starting a project, is what data the
HEASARC has on one of the objects you typically study. Our
index query video shows how
you can find which HEASARC tables have data on 3c273, and how you can
then query any of these.
The archetypical HEASARC archive session is to get
some data to analyze. To get data from a mission you first
need to specify the table you are interested in. Depending upon
whether you already know, there are several different ways to specify
a which table you want to query. Then you find the rows that match
the observations you are interested in and get the associated data.
table selection and
query to data download
videos illustrate how you can be downloading data in just a few seconds.
Cross-correlations are easy in Xamin and the
illustrates how you can correlate ROSAT and ASCA observations, including
setting your own correlation radius and specifying non-positional constraints
on the query.
Xamin allows some fairly sophisticated analysis in queries. We plot the
average flux of ROSAT FSC sources as a function of galactic latitude in our
parameters and plotting video.
In this query none of the original rows in the table are used, only parameters
the user defined.
While correlations are great, anticorrelations -- where we find the rows in
a table which don't have a corresponding entry in another table can also be
useful, e.g., when thinking about which targets to propose for. We illustrate
uploading a list of targets and doing the anticorrelation in our
proposal prep video.
If you set up a user account Xamin can tell you when things change.
shows how you can be notified whenever something happens to one of your
Many missions have a rich hierarchy of data products. Our
product control video
shows how you can filter for only the products you want. The
shows how you can create a shell script to download data products offline from
your web session.
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.
||Main window of the interface. Compose and initiate
||Query to ... Table
||Show table results. May show data products.
| SkyView Preview
|| Show SkyViewpreview images
||Query to ... Plot
||Specify plot parameters.
||Submit on Plot Control Pane
||Show plot results.
||Product selection on Table pane
||Filter and download products.
||Keyword search in Tables Explorer
||Show tables matching keyword search.
||Session menu/User tables-info
||Manage user account and tables.
||User account pane Frequency column (for saved tables)
||Set schedule to monitor query result for changes.
||Provide feedback and bug reports
||Table pane/Edit products
||Select which product to retrieve for a table
This reference document describes each of the panes of the interface
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.
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
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.
- Login. This will initiate a login process where a user may log
into an existing account or create a new one. The login service
is independent of
Xamin and may be used for other services.
- Logout. Log out of the current account. Disabled if not
- Upload. This will bring up the file upload menu which allows
you to upload source files and tables in a variety of format.
Disabled if not logged in.
- Save session. Save the current configuration of your Xamin
session. Users can save a session into a browser cookie
of whether or not they are logged in, but most options will not
work unless the
user is logged in.
- Restore session. Restore the configuration of your Xamin
session from a previous state that you have saved.
- User tables-info. Show the account summary page which allows
you to see and delete your saved tables or session
The Options Menu
This menu affects the way each query is interpreted and the results
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
Check the name resolvers that you would like to be used in
converting names to 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
- Anticorrelate against last table. Check this box if you wish
to find fields in the earlier tables which do not match against
the last table, e.g., targets seen by ROSAT that have NOT been
observed by Chandra.
- 1st versus all tables. If you don't explicitly specify the
fields to be shown (by opening the Parameters Explorer), this
controls whether you get rows from only the first table or all
the tables in the correlation.
- 1st table. In a cross-correlation show fields only from
the first table in the correlation.
- All tables. In a cross-correlation show fields from all
tables in the correlation.\
Select the desired output format.
- Grid. A sortable grid output that includes product information
if requested. This format is not recommended for large outputs.
This is the default output format.
- Aligned text. A text table with all columns aligned.
- Streaming text. A text table with no extra white space.
- VOTable. An IVOA XML standard.
- FITS. Using FITS binary tables.
- Excel. An Excel .xls file.
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.
- Download. When this is checked you should get a browser download
dialog to save the results on your local machine.
- New pane. The default is to show text outputs in a pane in the
Xamin browser window.
- External. Display the results in a different browser window
than the form is on. The browser decides whether to use windows
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.
- Standard versus All fields. If you do not set the output
fields, then do you want to see the standard set of parameters
or all parameters from the table. Note that setting this
parameter only has an effect if it is done before you open the
Parameter Constraints for the currently selected tables. If the
Parameter Constraints have been viewed, then the order specified
there will be used.
- Include offsets. Check this if you want to see fields added
to the results which give the offsets between rows and the
position specified, or between the rows in the of the different
tables in a cross-correlation. Note that an offset field is not
generated when you enter more than a single target position.
E.g., if you ask for everything near either 3c273 and 3c279 no
offset will be given. You may wish to disable this field when
you are using aggregate functions in dynamically created fields
or constraints. The offset field may defeat the intended
grouping of the data.
- Include system fields. Certain system parameters are added to
most tables but are not normally shown to users. If you wish to
see these parameters then check this box. Normally this is
desirable if you are going to save the results of a query as a
user table and this flag is automatically set for such queries.
Select the products that you will show for the user. Products are
visible only when using the grid output.
- Archive. Data sets linked to the tables you are
quering. Set by default.
- Table links. Table links are simply queries, within Xamin,
of tables with information that may be related to the
current table. E.g., a link may include data from
another mission in the same region.
- Bibliography. Published literature associated with a given
observation or table entry.
- NED/SIMBAD/SkyView links. Queries of popular services near
the position of a given row.
- Distinct rows only. By default a query may show many
identical rows. E.g., you might have asked to see just the
instrument used by ROSAT in each of a set of observations. This
option suppresses duplicate rows so that you will get just one
entry. A common case for using this is when doing
cross-correlations where you do not wish to see any fields from
one of the participating tables. It is not enabled by default
since it can substantially increase query time.
- Survey Imgs. Set SkyView surveys that will be previewed
when you do a query that specifies a single position. A comma-separated
list of SkyView survey names should be given. The default is DSS,RASS
which gives previews using the DSS and RASS surveys.
- Row limit. Only show the first N rows in a query. Clear this
entry or set a negative value to remove the limit. Set to 0 to
suppress running the query. This can be useful if a user wishes
to check constraint syntax.
- Time limit. Set a time limit for the query. There are two
checks done here. Before each query is set an estimated time for
the query is calculated. The query will not be performed if the
estimate exceeds the time. When the query is started, a timeout
for the given limit is set and the query will be interrupted and
fail if it exceeds the limit.
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.
- Show cost estimates. This will show the estimated cost for
running the query. This is extremely rough and includes only the
query cost, not the time for downloads or rendering.
- Show command arguments. The Xamin Web interface uses the
Xamin CLI libary. Show the arguments used in the underlying
query command. You can use this to help build scripts using the
- Show runtime settings. Show all of the runtime settings in the
Xamin CLI command, including the run time arguments and the
- Show generated SQL. Show the SQL generated for the query.
- Time query. Show the actual execution time for the query.
Unlike the other data controlled in this menu, this is computed
on the client side and is the actual time between the initial
dispatch of the query and final receipt of information back from
the server. It does not include the time to render the result in
This allow the user to change the overall appearance of the GUI.
- Standard (blue). The default theme with a typically light blue
- Gray. A similar theme based on gray.
- Accessible. A theme that enhances the constrast between elements.
The Help Menu
This menu allows you to get to several different help resources.
- Xamin Web tutorial and guide. A link to this document.
- Command Line Guide. How to get and use the command line version of Xamin.
- Xamin System Guide. An overview of the Xamin design and implementation
- FAQ. What users have asked before?
- E-mail comments. A link to the E-mail feedback.
- Bug report/Feature Request. The Xamin Feedback page.
- Release notes. Changes in the current version of Xamin
- Version. The release notes for the current version of
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
- 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.
These four buttons are provided to clear/reset elements of the
- 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.
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
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
four 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.
Table uploads were added to the Tables Explorer in version 2.8
of Xamin and many of the screen captures in this document
do not yet reflect this capability.
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.
The HEASARC provides direct support for about 800 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 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
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
sophisticated 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
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.
Users can upload tables from their computers to be used in an Xamin query.
Without logging in, users can upload a single table, but if a user has
logged in any tables saved in previous or the current sessiont
are appended at the end of the table tree. These persistent 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.
Persistent 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
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
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
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.
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
Using the Tables Explorer upload
Starting in Xamin version 2.8, users can upload tables into queries
without having to log in. Use the file selection widget in the
upload feature to select a source list, CSV file or VOTable to be
uploaded. When you select a file,
the table 'Upload' will appear in the selected tables list. You can clear
the upload using the button next to the file selection widget or by deleting
the Upload table in the selected tables tree.
Uploaded tables are treated just like other tables. You can
make selections based upon the fields in the table and do correlations
with other tables. E.g., if you want to find all of the XMM observations for
a list of objects, then create a source list for this list, and you can correlate
the upload with the XMMMaster catalog.
Files can also be uploaded using the Upload option in the Session menu, but you
will need to be logged into your Xamin account to use them.
There are some limits on queries when you use the upload capability of the
Tables Explorer. You can only upload a single table in a given query,
plotting functions are not supported, and you cannot save the state of the
query form. These limits arise the nature of how files are uploaded in
from Web forms. However none of these limits apply to files you upload into
your Xamin user area. This approach also allows characters other than commas to be used
as the delimiters in CSV files.
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.
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
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.
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.
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
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 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.
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
After products are transferred to the shopping cart, users can
download products using its capabilities.
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
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
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
Finding WGET and CURL
The network utilities wget or curl are included with most
systems. To download wget or get more information visit
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 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.
User Accounts Pane
The user account pane is shown when a user logs in or
Session/User Tables--Info menu entry.
This pane shows the saved user tables and query configurations.
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.
Users can save tables either by uploading them (
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
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 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.
explorer pane is created when users select the
button in grid table result.
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
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.
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
||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 names||Names 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.
|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 may be specified in JD, MJD or ISO formats. Time ranges may be given.
|String matching ISO time formats. Positive numbers > 10000 are
treated as MJD times, (or JD if > 1000000)|
||The coordinate system used for input and output
||J2000, Galactic, B1950, E2000
||Case insensitive keyword match|
||HEASARC and Vizier table names
| Exact match for HEASARC tables, tokens including "/" are assumed to be Vizier tables. |
|Formats||The format for the output of a table query or correlation
||Text, Excel, FITS, VOTable||Case-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
|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.
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.|
|Constraints||Constraints on the query. If a literal string value is used it must be enclosed in single quotes.
|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.