The Xamin Plot Interface

This document describes how to use the Xamin Plot interface to create one, two or three dimensional plots based on selections you have made in the Query Window. The first part of the document provides tutorials that illustrate the major features of the Plot Interface. A comprehensive reference manual which discusses each element of the interface is currently under construction and will be added in the near future.

Additional information on Xamin is available in other documents. Help for the Xamin web interface is in the Web Users Guide. 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.

The Xamin plot web interface uses the plotting capabilities of the STILTS library developed by Mark Taylor. Plots may be created in a command line environment by invoking the STILTS library directly. To script plotting of query results, use the facilities of the Xamin CLI interface to generate tables of results, and then plot them using STILTS.

An Xamin Plot Tutorial

We'll go through a couple of examples here.

Simple Plot

Let's start with a simple example that shows right ascension vs exposure of 3C273 observations in the ROSAT Archival Data.

1. Start by selecting ROSAT Archival Data (rosmaster) in the Select Tables section of the Query Window.

2. Enter target 3C273 in the Position input box.

3. Click the Plot button

4 The Plot Control form is displayed. This form allows you to plot query data in two or three dimensions.

Now we can start making selections to create our plot.

1. First select the fields you want to plot. Select ra from the pulldown menus for the X axis, exposure for the Y axis. The pulldown menu will include all numeric fields for the selected table. The small green dots indicate fields that were used in the table query.

2. The appearance of plots can be adjusted by selecting the various options (eg., plot title, plot marker size, shape, color) in the Image Options tab. Various output formats can also be selected in this tab. We'll leave the selections at the default values for this first plot.

3. Click the Submit button.

The simple ra vs exposure plot with the default Image Options selections for a rosmaster table of target 3C273 is shown below.

Error bars

In this example we'll demonstrate plotting error bars for a ra vs count_rate plot for xray observations of target eta car. We've already selected the Xray Master Table (xray) and eta car in Query Window and clicked Plot to display the Plot Control form.

1. Select ra from the X axis pulldown menu

2. Select count_rate from the Y axis pulldown menu

3. Click the Set error bars expansion triangle in the Y axis section to expose the error input box.

4. An expression or a column name can be entered can be entered into the error input box. If the column name selected from the pulldown menu has an associated error field it will automatically be displayed in the input box. In our example the count_rate field has an associated error field (count_rate_error) so it appears in the box. A different column name or expression can be entered instead. If you do not want to display error bars simply click the expansion triagle to turn this option off

5. Because we know the data values cover a large range we have checked the Log option to scale the data. Click the Submit button to display the plot.

Below is the plot for ra vs count_rate with count_rate error bars for eta car observations in the Xray Master Table.

Samples

Samples allow users to group or further define the data points on the plot using expressions based on any column (numeric or otherwise) in the current table. Sample expressions may be the name of a boolean-valued column or a boolean-valued expression, typically based on a column value. Rows for which the expression evaluates true will be included in the plot.

To illustrate the use of Samples and some other plot options we'll go through an example step by step start to finish. The object will be to plot gamma ray bursts that are in the Swift Master Catalog for the years 2009 and 20010.

1. We'll start at the Query Window and select the Swift Master Catalog (swiftmastr) from the Select Tables section .

2. Enter a Time range of 2009-01-01 to 2010-12-31

3. Click the Plot button

4. The Plot Control form for the Swift Master catalog will appear.

Now we will make selections to plot all the observations in the Swift Master Catalog for the years 2009-2010.

5. Select ra in the column pulldown menu for the X axis

6. Select dec in the column pulldown menu for the Y axis

7. Since most likely the number of rows to display (which also applies to the table query) is set to the default value we will override it by clcking the Plot all rows option

8. Give the plot a more descriptive title in the Plot title box and click the Submit button

A ra x dec plot of all Swift Master Catalog observations for 2009-2010 will appear.

Now we will sample the data to plot gamma ray bursts.

1. Select the Samples tab

2. Enter grb_flag == 'Y' in the Expression box

3. The Expression Syntax Help button will provide examples of expressions that can be used for sampling.

4. The Parameter Name Help button will give you a list of all fields for the current table

5. Enter a description of the Sample. The default is the expression string

6. Select a color (or use the default)

A ra x dec plot of all gamma-ray bursts observed by Swift in 2009-2010 will appear.

Now if we want to see the distribution of bursts compared to the rest of the observed sources we can add another sample

1. Click the Add sample button and a new sample section will appear below the first.

2. Enter the expression grb_flag != 'Y'

3. Enter the description non GRBs as Sample label

4. Choose a contrasting color, if desired

A ra x dec plot of all gamma-ray bursts and non gamma-ray bursts observed by Swift in 2009-2010 will appear.

3D Plotting

Now that you have the basics of 2D plotting down it's easy to take the one extra step to create a 3D plot.

This tutorial demonstrates how to plot location and duration values of gamma ray bursts:

1. Select the Gamma-Ray Bursts Catalog (grbcat) from the Query Window

2. Click the Plot button

3. In the resulting Plot Control form select ra from the pulldown menu for the X axis and dec for the Y axis

4. Select T50 for the Z axis

5. Be sure to check the Plot all rows option in the Image Options tab so we see all bursts. Make any other desired changes. We've changed the plot title and made color and shape changes for the plot markers. Click Submit

A ra x dec x T50 plot of gamma-ray bursts of various durations are distributed in space will appear.

Histogram

This example show how to plot a histogram from your search query. We'll use the Gamma-Ray Bursts Catalog again and bin the %50 Burst duration values.

1. Click the Histogram Tab to display the Histogram Form.

2. Select T50 for the X axis

3. Click the Log checkbox for the Y axis

4. Check the Plot all rowschckbox in the Image Options tab and make any other desired changes.

5. Submit the form

Here is the histogram