Skip to the navigation links
Last modified: 25 Jan 2010
Where are the PDFs?

Introduction to the Analysis Menu

CIAO 4.2 Science Threads


Last Update: 25 Jan 2010 - reviewed for CIAO 4.2: no changes


The "Analysis" menu is a component of the CIAO graphical user interface (GUI) applications that makes it possible to run command-line tools from within the GUI. A default configuration file is shipped with CIAO, but it is easy to define a custom menu suited to your analysis.

Related Links:


Get Started

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

The format of the file used to define layout of the analysis menu matchs ds9's Analysis Menu Definition Language, so custom menus will work in both the CIAO GUIs and ds9.

The simplest way to change the layout of the Analysis menu is to make a copy of the default file:

unix% cp $ASCDS_INSTALL/bin/ciao.ans my_ciao.ans

Then add customizations to my_ciao.ans.

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.

Format of the ciao.ans File

This section describes the formatting options that may be used to edit existing and create new menu items.

Menu Entries

The generic format for menu entries is:

   <command name> [ # tip <tooltip>]
  • <command name> - the name that appears in the menu entry.
  • <tooltip> (optional) - the tool tip for the entry; this option may not work properly in ds9. A tool tip is the message that appears when the mouse hovers over the menu item for a short time.
  • <template> - the file format for which the menu item is active (e.g. *, *.fits, *.txt).
  • menu - specifies that the entry is a menu item. ds9 also allows a bind option, but it is not supported by the CIAO GUIs.
  • <command> - the command to execute, including any supported macro expansions.

To illustrate, look at the first entry in the default ciao.ans file:

unix% more $ASCDS_INSTALL/bin/ciao.ans
# ciao.ans   - Analysis Menu Definition file for CIAO

Edit Parameter File #tip Parameter editor GUI (peg)
peg "$entry(Parameter file name)" infile=$filename | $null



This entry creates a menu item titled "Edit Parameter File" with the tool tip "Parameter editor GUI (peg)". This option is available for all filetypes (*). The command that is executed uses three macros: $entry(<text>), $filename, and $null; see the next section for an explanation of what the macros do.

The three dashes (---) after the entry create a separator in the menu; see the Submenus and Separators section.

The resulting menu item is first in the Analysis menu, as shown in Figure 1.

[Thumbnail image: The menu is expanded to show the menu items and submenus.]

[Version: full-size]

[Print media version: The menu is expanded to show the menu items and submenus.]

Figure 1: Expanded Analysis menu

Long menus do not automatically wrap. They must be manually split into smaller lists, e.g. the "A-C", "D", and "E-Z" tool menus.


When command-line macros are used in a menu entry, they are expanded before the command is executed. The following macros may be used in the analysis menu:

Macro Function
$filename Substitutes the current filename from the GUI.
$filename(root) Same as $filename but it also removes any specified path, leaving only the root of the filename.
$entry(<text>) Displays a text entry dialog with the specified message ("<text>"). If the "Ok" button is selected, then the rest of the command will be executed with the entered text.
$message([ok|okcancel|yesno],<text>) Displays a message dialog box with the specified option buttons and text. The remainder of the command will only be executed if "ok" or "yes" is selected.
$text The output of the specified command will be displayed in a window (taskmonitor when run from a CIAO GUI). It should be the last macro of a command.
$null Included for compatability with ds9. The macro tells ds9 that it should not wait for the completion status or output of the command. It is ignored by the CIAO GUIs.

Submenus and Separators

There are two ways to add organization to the analysis menu: nested submenus and separators.

  • Submenus

    Menu items may be places in submenus which can be nested up to ten deep. The menu format is:

    hmenu <name> [# tip <tooltip>] 
     ..(menu contents)..
    • <name> - text to appear in the menu.
    • <tooltip> (optional) - text for the tool tip.

    Note that indentation is not important and that hmenu/endhmenu pairs can appear within a hmenu section. The ciao.ans file has several examples of this syntax in use:

    unix% more $ASCDS_INSTALL/bin/ciao.ans
    # start "Tools" menu
      hmenu Tools - alphabetical # tip Complete list of CIAO tools
       hmenu A-C
          acis_detect_afterglow  # tip Identify and flag cosmic ray afterglows
          *.fits *.qp
          peg acis_detect_afterglow infile=$filename | $null
          (rest of A-C tools listed)
       hmenu D
          peg acis_detect_afterglow infile=$filename | $null
          (D tools listed)
       hmenu E-Z
          (E-Z tools listed)
    # end "Tools" menu

    Figure 1 shows the "Tools - alphabetical" menu and the three submenus - "A-C", "D", and "E-Z" - which were created with the syntax shown.

  • Separators

    A separator is a dividing line in the menu. It is created by starting an empty line with three consecutive dashes (---):

    unix% more $ASCDS_INSTALL/bin/ciao.ans
    # ciao.ans   - Analysis Menu Definition file for CIAO
    Edit Parameter File #tip Parameter editor GUI (peg)
    peg "$entry(Parameter file name)" infile=$filename | $null
    hmenu GUI Applications #tip Launch a GUI application  
       ds9  # tip Imaging GUI

    A separator is created between the "Edit Parameter File" item and the "GUI Applications" menu, as shown in Figure 1.


It is also possible to create menu items that bring up a help dialog box. The syntax is straightforward:

help <help label>
  • help label - the label for the menu entry.
  • helptext - the text to be displayed in the dialog box. The text can extend over multiple lines.

To create a help item for Timing Analysis:

help Timing Analysis (help)
  Before creating a phase-binned spectrum,
  be sure to barycenter correct the data.

  Tool to use: axbary
  Files needed: level 2 event; ephemeris

When the item is selected (after the new my_ciao.ans file is loaded), the help text is displayed in a dialog box (Figure 2).

[The help information is displayed in an independent dialog box.]
[Print media version: The help information is displayed in an independent dialog box.]

Figure 2: Viewing a help item

The "OK" button closes the help box.

Creating a Menu Item

New menu items may be created for tasks that you use often. In this example, we added a new item that lists the FITS header in any file (i.e. there are no filetype restrictions):

unix% more my_ciao.ans
# my_ciao.ans  - Analysis Menu Definition file for CIAO

Edit Parameter File #tip Parameter editor GUI (peg)
peg "$entry(Parameter file name)" infile=$filename | $null


List Full Header # tip Runs dmlist with opt=header,raw
dmlist infile="$filename" outfile="" opt="header,raw" mode="hl" | $text



Figure 3 shows that the "List Full Header" item has been added to the Analysis menu, after the new my_ciao.ans file was loaded into the GUI.

[Thumbnail image: The "List Full Header" item is included in the Analysis Menu list.]

[Version: full-size]

[Print media version: The "List Full Header" item is included in the Analysis Menu list.]

Figure 3: The new menu item

The tool tip text defined in the menu file is shown when the mouse hovers over a menu item.

Loading a Customized File

The my_ciao.ans file may be loaded when the application is launched for any customizations to be made available:

unix% prism -t ./my_ciao.ans

This syntax is for the CIAO GUIs: prism and peg.

For ds9:

unix% ds9 -analysis ./my_ciao.ans

A file that displays nicely in prism may not be suitable for ds9 and vice-versa. It is possible to define a custom configuration file for each tool or analysis task, simply launching the one desired for each session.

To have my_ciao.ans be used as the new default file, place it in your home directory and rename it ciao.ans. This ensures that your customized menu will be available to all GUIs that are launched in the CIAO session. (When provided as a command-line option, the "my_ciao.ans" file will not be passed to new GUIs that are opened.) As described in the help file, the loading precedence is:

  • If the -t command-line option is specified, use the listed file
  • Check for the file ciao.ans in the user's home directory ($HOME/ciao.ans)
  • Check for the file CXCDSToolTable in the user's home directory ($HOME/CXCDSToolTable)
  • Look for $ASCDS_INSTALL/bin/ciao.ans
  • Look for $ASCDS_INSTALL/bin/CXCDSToolTable


03 Jan 2005 reviewed for CIAO 3.2: no changes
01 Dec 2005 reviewed for CIAO 3.3: no changes
01 Dec 2006 reviewed for CIAO 3.4: no changes
10 Jan 2008 reviewed for CIAO 4.0: no changes
15 Jun 2008 updated image display to place figures inline with text
06 Jan 2009 updated for CIAO 4.1: GUIs were rewritten in GTK, so some cosmetic changes (updated all thread images); "-toolmenu" option renamed to "-t"; moved the Loading a Customized File section to the end of the thread; added Why does my GUI look different? section
25 Jan 2010 reviewed for CIAO 4.2: no changes

Return to Threads Page: Top | All | Intro

Where are the PDFs?
Last modified: 25 Jan 2010