Description

In the simplest terms, prism is a graphical user interface (GUI) application for file browsing. It lists the extensions of a file and allows the user to view the header and data of each block. However, prism also offers many other analysis features: interactive plots of column data (including plotting errors and histograms), viewing of simple ascii file, table editing, on-the-fly column selection, image display, header editing, and integration with other CIAO analysis tools.

File formats

Prism will read in any file that is supported by the CIAO data model, and so DM filters and column specifiers (e.g. "ahelp dmsyntax") can be used when specifying a file to view. Prism can also display simple ASCII files, including those in RDB format. It uses the ascii2fits script to convert such files to FITS format and then displays the result (this conversion is done automatically). This means that the format for ASCII files must match that supported by ascii2fits (see "ahelp ascii2fits" for more information on the allowed formats).

Prism Settings

The Prism tool has a parameter file which can be edited either by using the CIAO command-line tools such as plist and pset or via the "Preferences..." option of the "Edit" menu. The parameter file is read each time the "Preferences" option is chosen.

Window Layout

The data display portion of prism is divided into three major sections: the blocks of a data file (top left window), the header of the selected block (top right window), and the data of the selected block (full lower window). A status window across the bottom of the application provides the user with various feedback messages. Leaving the mouse over a button or field for a few sections will reveal a pop-up "tool tip" that gives some information about it (as long as the quickhints parameter in prism's parameter file is set to yes).

User commands to prism are issued through the menu bar across the top of the application, from a pop-up menu (accessed by a the right button when the mouse is in the data field), or with keyboard shortcuts. Additionally, prism interacts with other CXC GUI applications via XPA commands, and can take advantage of the session support in CIAO (see "ahelp session").

Table display

Tables are displayed as columns, with the column name, units (if defined), and data type listed at the top of the data display. A horizontal scroll bar will appear if all the columns will not fit into the window at once. Vector columns - such as the CHIP, DET, and SKY columns in an event file - are not automatically expanded into their components. To see their contents, highlight the vector column using the left mouse button, and then go to the "Navigate" menu entry and select "Expand Column" (this option can also be found in the floating menu accessed by a right mouse click in the data window, or via the "CTRL+X" shortcut).

Viewing a subset of the table columns

There are two ways of viewing a subset of the columns in a table. The first is to use a DM filter (see "ahelp dmcols") to select the desired columns. The second is to select the required columns in Prism and then chose the "Reopen w/ Selected" option from the "File" menu (or use the CTRL+r shortcut).

Plotting columns

When a column has been selected it can be plotted using the Visualization menu. If two or three columns have been selected - note that selecting an unexpanded vector column counts as selecting all components of that column - then they can be plotted using the "Interactive Plot..." option. The first two columns are used as the "x" and "y" values of the plot and the third column - if selected - will be used as the symmetric error value for the "y" value.

If a table only contains two columns then they can be plotted without selection; the first column is taken as the "x" value and the second the "y" value. Similarly if it contains only three columns then they will be taken as the "x", "y", and "y error" values.

Viewing a histogram of a column

The "Histogram" option of the "Visualization" menu allows you to view a selected column as a histogram. When the option is selected a window will be displayed giving you control over the binning used to create the histogram. Selecting the "Apply" button will display the histogram using the chosen settings whilst keeping the "Histogram Preferences" window open, and so allow you to change the binning parameters; the "OK" button will create the histogram but close this window. Note that the rest of the Prism display will be unresponsive whilst the "Histogram Preferences" window is open.

There are two modes for selecting the binning used for the histogram. The default mode ("Specify Binning Parameter") is to use evenly spaced bins covering a given range where the minimum value, maximum value, and number of bins can be changed by the user. These fields are initially populated with the minimum and maximum values of the selected column and the value of prism's "histbins" parameter (50 by default). The alternative mode ("Specify Bin File") allows you to specify the name of an ASCII of FITS file which lists the lower and upper bounds of the bins to use for the binning. Once a file has been specified you are given the option of selecting which columns from the file should be used for the lower and upper bounds: for ASCII files the columns are referred to as "col1", "col2", ... (note that ASCII files are read in using the ascii2fits script and so need to conform to the layout described in "ahelp ascii2fits").

When a table block is opened then a background process is started to calculate the minimum and maximum values of the numeric columns. These numbers are then used to populate the minimum and maximum value fields in the histogram window. The rangerows and rangecols parameters - described below - can be used to control this calculation since it can take a non-negligible amount of time for large datasets.

If either rangecols or rangerows is set to 0 then no range calculations are performed, so the minimum and maximum fields will be left blank when the histogram option is selected. If both are set to -1 then the calculations are performed regardless of the number of rows or cols in the block. Otherwise the numbers of rows and cols must be less than the rangerows and rangecols values for the ranges to be found.

Exporting table data to ChIPS

The plotting and histogram options allow simple display of the data. For more complex manipulation or display you can export the selected data to a ChIPS session using the "Export data ..." item of the Visualization menu. This takes the currently-selected columns (or the whole file if none are selected) and copies it into a ChIPS session as the prism_data S-Lang variable (if no ChIPS session has already been created then one is started). The contents of prism_data are the same as if you had executed a readfile() command on the file and included any column filters; the following output shows the prism_data structure after exporting the time and sky columns of the file /data/chandra/evt2.fits:

  chips> print(prism_data)
  _filename        =  evt2.fits
  _path            =  /data/chandra/
  _filter          =  [2][cols time,sky]
  _filetype        =  4
  _header          =  String_Type[529]
  _ncols           =  3
  _nrows           =  21823
  time             =  Double_Type[21823]
  x                =  Float_Type[21823]
  y                =  Float_Type[21823]

Note that this currently does not work with image data, nor does it take notice of any row selection you might have made in Prism.

Image display

The default mode for viewing image data is to display a grid of values in which the bottom-left corner represents the lower-left pixel of the image, which matches the display of ds9. To revert to the previous behaviour, where the lower-left pixel is displayed in the first row/column of Prism's display, change the "imgdisplay" parameter of Prism to "no". If you change this parameter via Prism's "Preferences" menu then you need to reload the image block for the new value to have effect.

Editing data in tables and images

To perform cell editing on tables and images, the file must have write permission. CTRL-(left-click) on the desired cell to enter editing mode, then type in the new value. If you have the quickhints parameter set then you can find out this information by moving the mouse over a cell and then leaving it alone for a few seconds.

Valid modifications will result in the cell being changed and a message identifying the change will appear in the status box. Limited range, overflow, and type checking are provided; incorrect values will display an error dialog and a message in the status box. In addition, prism will automatically reset an invalid entry back to its previous value. To edit cell values of arrays or vector columns, expand the column (left-click, then CTRL-x) and enter cell editing mode in the data matrix that is displayed.

An undo option exists for cell edits via the "Edit" menu's "Undo Last Cell Edit" option. The undo option treats cell edits as a stack; that is, they are undone in reverse order (edits 1, 2, 3 will be undone as 3, 2, 1). When the "Undo Last Cell Edit" option is used, the most recently edited cell is changed back to its prior value and the status message box identifies the change.

Cell edits may only be undone while the window displaying the data is still open. If edits are made to a vector column in an expanded window and the window is closed, the edits will be removed from the undo stack. Appending rows or columns flushes edits to the output file and deletes the entries in the cell editing undo stack. In both these cases, the undo option will no longer be available for the changes.

Adding columns to a table

To append new columns to the open table extension, select the "Append Table Column..." option from the "Edit" menu and a dialog window will appear. Users may specify a scalar or array column type with the radio toggle. There are fields for the column name, data type, units, and description fields; if 'array' is selected, an additional field for the number of elements is provided. Click [OK] or [Apply] to add the column; a HISTORY keyword that column "colname" was added by prism is written to the block's header. Note that the values are not initialized to any specific value, so they may contain garbage.

Adding rows to a table

To append one or more rows to the open table extension, select the "Append Table Row(s)..." option from the "Edit" menu and a dialog will appear. Enter the number of rows to append and click on [OK] or [Apply]. Note that the values are initialized to zero. A HISTORY keyword stating that the selected number of rows were added by prism is written to the block's header.

Recently accessed files list

Selecting the "Open List" option from the "File" menu displays a list of (up to) the last 10 accessed files. Selecting any of the specified files loads it into prism again. The file history is stored in a $HOME/.prism.filelist file, which the tool checks whenever a file is opened. If the file is already in the list, the list is not modified; if not, the file is added to the top of the list. Filter specifications and path names are considered part of the file name.