Last modified: 18 Nov 2019

URL: https://cxc.cfa.harvard.edu/ciao/threads/prism_intro/

Introduction to Prism

CIAO 4.12 Science Threads


Overview

Synopsis:

prism is a graphical user interface (GUI) application for file browsing and simple editing. It lists the extensions of a file and allows the user to view the header and data of each block. Prism offers many analysis features: interactive plots of column data, table editing, column-filtered viewing, and image display.

Last Update: 18 Nov 2019 - Updated to reflect transition from ChIPS to Matplotlib and from GTK2 (CIAO 4.11 and earlier) to GTK3 (which is used in CIAO 4.12), which affects the look of the user interface.


Contents


Getting Started

For illustration, this thread utilizes the ObsID 1843 (ACIS-I, G21.5-0.9) data that was downloaded in the How to Download Chandra Data from the Archive thread.

If this is your first time using CIAO, please read the Starting CIAO thread to ensure that your environment is configured properly.

Unlike the CIAO tools, prism does not have a parameter file. The GUI preferences - set from the "Edit → Preferences" menu - are stored in $HOME/.prismrc. The options are described in the ahelp file.

Why does my GUI look different?

The CIAO GUIs use the default GTK theme specified on each user's machine to determine how the GUI is displayed (e.g. gray background with selected items in blue). Your GUI may look different than the one shown in screenshots in this thread, but the functionality is the same.

The help file on guis has instructions on how to change the default theme.


Launching prism

There are several options for starting up prism:

  • Do not give any arguments:

    unix% prism &
    

    An empty prism GUI (Figure 1) is opened.

    Figure 1: GUI before loading a file

    [Thumbnail image: The main window of the GUI is empty and the status window indicates that blank tab was created.]

    [Version: full-size]

    [Print media version: The main window of the GUI is empty and the status window indicates that blank tab was created.]

    Figure 1: GUI before loading a file

    Open the desired file via "Open" from the "File" menu.

    A list of recently accessed files is maintained by prism and can be found in the "File → Recent" submenu. This displays a list of up to the last 10 files viewed; selecting any of the files reloads it. When storing the recently-viewed files, the path is considered part of the filename.

  • Specify the file name when prism is launched:

    unix% prism acisf01843N003_evt2.fits &
    

Once a file is loaded, the GUI displays the information for that file, such as the data and header. Figure 2 shows the information for the file acisf01843N003_evt2.fits.

Figure 2: prism GUI after loading an event file

[Thumbnail image: The main window of the GUI is displays the event data for ObsID 1843.]

[Version: full-size]

[Print media version: The main window of the GUI is displays the event data for ObsID 1843.]

Figure 2: prism GUI after loading an event file

The tab indicates the file name and an icon indicating whether you have write access. In this case, since the file is compressed (*.gz) it can not be edited in place, so the tab contains a red cross.


The Basic Display

The file browser contains four main regions, as seen in Figure 2. The upper left shows the extensions, also called blocks, contained in the FITS file; the "interesting" block (e.g. EVENTS for an event file, SPECTRUM for a PHA file) is automatically chosen to be displayed. The upper right shows the header information of the block that's currently selected. The body of the GUI displays the data contents of the current block. A status window across the bottom of the application provides various feedback messages.

The icon at the left edge of the file tab - a locked padlock in Figure 2 - indicates whether the file has write permission or not. This is discussed further in the table editing section.

Note that some columns are vectors (e.g. chip and sky). By default, they are expanded inline in the data section. This is a data display option which may be set and saved to the preferences file.

Tabbed File Viewing

It is possible to open several files in tabbed frames in a single instance of prism.

To open a file in a new tab, use the "File → Open New Tab" menu to select the file to open. There is also a "File → Recent New Tab" option which opens a recently-viewed file in a new tab. Figure 3 shows two files loaded in separate tabs.

Figure 3: Opening files in tabs

[Thumbnail image: Two files are open in separate tabs in the same prism GUI]

[Version: full-size]

[Print media version: Two files are open in separate tabs in the same prism GUI]

Figure 3: Opening files in tabs


Viewing ASCII Data

Prism is able to display simple ASCII files through the Data Model ASCII kernel. The files are opened in the same manner as FITS tables:

unix% prism input.txt

All the features of prism can be used with ASCII data, e.g. table editing, plotting.


The Visualization Toolbar

Tasks which used to be run from a "Visualization" menu are now available from a toolbar in data display section of the GUI, which is outlined in Figure 4.

Figure 4: The prism toolbar

[Thumbnail image: The toolbar is outlined with a red box.]

[Version: full-size]

[Print media version: The toolbar is outlined with a red box.]

Figure 4: The prism toolbar

There are three menus for visualizing the data: "Plot", "Histogram", and "Image".

Each of the data visualization menus - "Plot", "Histogram", and "Image" - has two options: "Quick" and "Interactive".

  • Quick: takes the column(s) which are selected and makes a plot, histogram, or image with default settings.

  • Interactive: opens a window which allows you to change the selected columns and customize the output: linestyle, symbols, colors, etc. After the plot is created, the options window can be used to replot as often as desired by adjusting options and clicking "Apply". This allows the user to easily add errors to the plot, choose a different column, or overplot additional data, among other options.

Either option may be accessed from the drop-down menu by each visualization method. There is also a button that launches each method with the option defined in the preferences; by default, the plot and image buttons open the "Interactive" window and the histogram button creates a quick histogram.

Plotting Data

Any two or three columns of data may be plotted within. This example will use the "Interactive" method of plotting.

Open the aspect solution file, pcadf084271087N003_asol1.fits, either in a new tab or within the existing one.

unix% prism pcadf084271087N003_asol1.fits &
  1. Highlight the desired two columns for plotting by clicking on the column name; the first column selected will be plotted along the x-axis, the second along the y-axis. In this example, ra and dec are plotted.
  2. Click the "Plot" button to open the Plot Settings window. Alternately, you could choose the "Plot → Quick Plot" option.

  3. Set the plot options. For this plot, the line style is set to "shortdash" and the symbol style is set to "none". The line color is changed to red (#f00f00); uncheck the "Default" box and then click the square to select the line color. Figure 5 shows the set options.

    Figure 5: Setting plot options

    [Thumbnail image: The line is set to be short, red dashes and the symbols are turned off.]

    [Version: full-size]

    [Print media version: The line is set to be short, red dashes and the symbols are turned off.]

    Figure 5: Setting plot options

    The default setting is to clear any plots in the current window before plotting the data.

  4. Click "Apply" to create the plot and leave the options window open.

The plot of telescope RA vs. Dec is shown in Figure 6.

Figure 6: Plot of RA vs Dec

[Thumbnail image: A Lissajous curve with a short, nlue dashed line.]

[Version: full-size]

[Print media version: A Lissajous curve with a short, nlue dashed line.]

Figure 6: Plot of RA vs Dec

Plotting RA vs Dec reveals the telescope dither pattern (a Lissajous curve).

The plot settings window can be used to change or add to the plot options. To make a plot of time vs RA, choose "time" from the "Curve X" menu and "ra" from the "Curve Y" menu. The menus are populated with the columns from the data file.

After changing the line style to "solid" and setting the behavior to "New Window", click "Apply". A new plot is created, as shown in Figure 7.

Figure 7: Plot of time va RA

[Thumbnail image: A blue curve which is roughly sinusoidal.]

[Version: full-size]

[Print media version: A blue curve which is roughly sinusoidal.]

Figure 7: Plot of time va RA

The plot of time vs RA shows one direction of the dither pattern over time.

Choose "OK" to close the plotting window when you are done.


Creating Images

Any two columns of data may be binned into an image and then displayed.

Open the event file, acisf01843N003_evt2.fits, either in a new tab or within the existing one.

  1. Highlight the desired two columns for binning by left-clicking on them. In this example, the x and y (sky) columns will be used.
  2. Select the "Image → Quick Image" option.

ds9 is launched with the image loaded (Figure 8).

Figure 8: An image in (x,y) coordinates

[Thumbnail image: The image of all six chips of the data is displayed in ds9 in greyscale]

[Version: full-size]

[Print media version: The image of all six chips of the data is displayed in ds9 in greyscale]

Figure 8: An image in (x,y) coordinates

The color scale has been changed to log after the display was created by prism.

If the "Image → Interactive Image" option had been selected then the default binning factor can be changed (Figure 9).

Figure 9: Setting imaging options

[A window offering several options: choice of XPA access point (defaults to "ds9"), the default columns to select (empty for both X and Y), and the default binning values (set to 8 for both axes).]
[Print media version: A window offering several options: choice of XPA access point (defaults to "ds9"), the default columns to select (empty for both X and Y), and the default binning values (set to 8 for both axes).]

Figure 9: Setting imaging options


Make a Histogram

A histogram is made from a single column. This example will use the "Quick" method of making a histogram.

The event file, acisf01843N003_evt2.fits, should still be loaded from the image example. If it is not, open it in prism again.

  1. Highlight the desired column for the histogram by clicking on the column name. The energy column is used in this example.
  2. Select the "Histogram → Quick Histogram" option.

A window containing the histogram (Figure 10) is opened.

Figure 10: Histogram of energy (eV)

[Thumbnail image: A step histogram with a solid blue line.]

[Version: full-size]

[Print media version: A step histogram with a solid blue line.]

Figure 10: Histogram of energy (eV)

This histogram shows the distribution of counts as a function of energy.

The default histogram binning is automatically selected. To change the selected column, or customize the display, use the "Histogram → Interactive Histogram" option.


Table Editing

To edit a table, you must have write permission for the file. The icon at the left edge of the file tab indicates whether the file has write permission (notepad) or not (lock). The "locked" icon will look something like the following (although it depends on the system and GtK themes that are installed):

[The tab for the file starts with a padlock icon]

Since prism currently does not support an undo option, all files opened in prism are locked to editing by default. Click the lock to unlock the file for editing or use the "Edit → Enable File Editing" menu option. The icon changes to a notepad when editing is enabled (as shown in Figure 11).

When switching to edit mode, users will be asked whether they wish to edit the current file in place, to make a copy of the file and edit it, or cancel to return to read-only mode.

Cell Editing

To change the value of a cell, click on it and enter the new value. Collapsed vector or array columns must be expanded before they can be edited.

Figure 11: Selecting a table entry for editing

[Thumbnail image: The second cell in the chipx column is highlighted for editing]

[Version: full-size]

[Print media version: The second cell in the chipx column is highlighted for editing]

Figure 11: Selecting a table entry for editing

On the first click, the cell contents are selected (in this case the 962 value for the second row of the chip(chipx)). Type to replace the information with a new value.

In this case the editing is being done to a copy of the original file (so the file name has changed in the tab from Figure 2).

While in editing mode, <TAB>, <SHIFT>-<TAB>, and the arrow keys may be used to move through the rows and columns to select different cells.

When a new value is supplied (i.e. after pressing "enter"), data type and range validation (if appropriate) are performed. If the change is invalid - e.g. a string provided for an integer column - the cell is highlighted in red (Figure 12). The status area also displays a message to indicate if a value had changed or a reason if an edited value did not change. In Figure 12, the error reads

Wed 20-Nov 10:17:49 Unable to convert dog to datatype short    (previous value=962)

The user must manually correct the error in the value.

Figure 12: Entering an incorrect cell value

[Thumbnail image: The cell with the invalid value (of "dog") has been highlighted in red, and the invalid text is also colored red.]

[Version: full-size]

[Print media version: The cell with the invalid value (of "dog") has been highlighted in red, and the invalid text is also colored red.]

Figure 12: Entering an incorrect cell value

In addition to the visual cue, the status window reports that there was a problem with the supplied value.


Append a Column or Row

  1. To append a new column to the open table extension, select the "Append Column" from the "Edit" menu in the toolbar and a window (Figure 13) will appear. There are fields for the column name, units, and description fields, as well as a dropdown menu to set the data type. If "Array" or "Vector" is selected, an additional field specifies the number of array elements or vector dimensions.

    Figure 13: Append Column to Table window

    [Thumbnail image: The Append Column to Table window has the column name, description, data type, and default value set.]

    [Version: full-size]

    [Print media version: The Append Column to Table window has the column name, description, data type, and default value set.]

    Figure 13: Append Column to Table window

    A value of "2" will be used to seed the new column.

    Click "OK" to add the column (Figure 14).

    Figure 14: Viewing the new column

    [Thumbnail image: A new column named NEW_COLUMN has been added with all values set to 2]

    [Version: full-size]

    [Print media version: A new column named NEW_COLUMN has been added with all values set to 2]

    Figure 14: Viewing the new column

    The new column is added to the end of the column listing. Note that the icon in the tab has also changed.

  2. To append a new row to the open table extension, select the "Append Row" from the "Edit" menu in the toolbar and a window (Figure 15) will appear. The new row can be seeded with the values of an existing row - chosen by the selector box or slider - or it can be created empty.

    Figure 15: Append Row to Table window

    [The Append Row to Table window has the initial row values set.]
    [Print media version: The Append Row to Table window has the initial row values set.]

    Figure 15: Append Row to Table window

    The new row will be created with all zero values (the default behavior is to copy the first row).

    Click "OK" to add the row (Figure 16).

    Figure 16: Viewing the new row

    [Thumbnail image: A new row has been added with all values set to 0]

    [Version: full-size]

    [Print media version: A new row has been added with all values set to 0]

    Figure 16: Viewing the new row

    The new row is added as the last row in the file.


Editing Header Keywords

In the Header Keywords section of prism there are two buttons: "Add" and "Delete". Select "Add" and the Add Header Keyword window (Figure 17) opens. There are 4 text fields - keyword name, value, units, and comment string - as well as a dropdown menu to set the type.

Figure 17: Add Header Keyword window

[The Add Header Keyword window has the keyword name, description, comment, and type set.]
[Print media version: The Add Header Keyword window has the keyword name, description, comment, and type set.]

Figure 17: Add Header Keyword window

The new keyword will be a string type called NEWKEY with the value "A new keyword" and a comment of "added via prism" (the default values are blank).

Click "OK" to add the keyword (Figure 18).

Figure 18: Viewing the new keyword

[Thumbnail image: The keyword NEWKEY has been added to the header.]

[Version: full-size]

[Print media version: The keyword NEWKEY has been added to the header.]

Figure 18: Viewing the new keyword

The new keyword (NEWKEY) is added as the last keyword before the processing history section of the header.


The Analysis Menu

The "Analysis" menu allows you to launch other CIAO tools from within prism; see the Introduction to the Analysis Menu thread for more information.


Closing prism

Prism and any remaining open windows that it launched may be closed by choosing "Exit" from the "File" menu.


History

14 Dec 2004 reviewed for CIAO 3.2: no changes
01 Dec 2005 reviewed for CIAO 3.3: no changes
01 Dec 2006 updated for CIAO 3.4: ChIPS version
10 Jan 2008 updated for CIAO 4.0: in "Viewing ASCII data" section, ascii2fits script has been replaced by the Data Model ASCII kernel; parameter file updates; ChIPS syntax updated for version 4.0; filenames and images updated for reprocessed data (version N003 files)
13 Jun 2008 updated image display to place figures inline with text
09 Jan 2009 updated for CIAO 4.1: prism was rewritten in GTK, so some cosmetic changes (updated all thread images); the GUI has a preferences file instead of a parameter file; added Tabbed File Viewing section; undo last cell edit and column-filtered viewing are not available; new interactive options for making plots, histograms, and images; added Why does my GUI look different? section
25 Jan 2010 reviewed for CIAO 4.2: no changes
11 Jan 2011 reviewed for CIAO 4.3: no changes
19 Jan 2012 reviewed for CIAO 4.4: added a section on modifying plots with the ChIPS GUI
03 Dec 2012 Review for CIAO 4.5; updated all screen shots for lastest GUI; updated file versions.
03 Dec 2013 Review for CIAO 4.6; table edition section needs further review.
22 Dec 2014 Review for CIAO 4.7; added more information about switching between read-only and edit modes.
18 Nov 2019 Updated to reflect transition from ChIPS to Matplotlib and from GTK2 (CIAO 4.11 and earlier) to GTK3 (which is used in CIAO 4.12), which affects the look of the user interface.