Introduction to the Analysis Menu
CIAO 4.12 Science Threads
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.
- dax: a suite of scripts that allows users to run common CIAO tasks from the Analysis Menu.
- Introduction to Peg: the parameter editor GUI is used to launch tools from the Analysis menu.
Last Update: 23 Dec 2016 - Reviewed for CIAO 4.9; no changes.
- Get Started
- Format of the ciao.ans File
- Creating a Menu Item
- Loading a Customized File
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.
The generic format for menu entries is:
<command name> [ # tip <tooltip>] <template> menu <command>
- <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) * menu peg "$entry(Parameter file name)" infile=$filename | $null --- ..cut..
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.
Figure 1: Expanded Analysis menu
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:
|$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.
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).. endhmenu
- <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 ..cut.. # 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 menu peg acis_detect_afterglow infile=$filename | $null (rest of A-C tools listed) endhmenu hmenu D peg acis_detect_afterglow infile=$filename | $null (D tools listed) endhmenu hmenu E-Z (E-Z tools listed) endhmenu endhmenu # end "Tools" menu ..cut..
Figure 1 shows the "Tools - alphabetical" menu and the three submenus - "A-C", "D", and "E-Z" - which were created with the syntax shown.
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) * menu peg "$entry(Parameter file name)" infile=$filename | $null --- hmenu GUI Applications #tip Launch a GUI application ds9 # tip Imaging GUI ..cut..
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> <helptext> endhelp
- 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 endhelp
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).
Figure 2: Viewing a help item
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) * menu peg "$entry(Parameter file name)" infile=$filename | $null --- List Full Header # tip Runs dmlist with opt=header,raw * menu dmlist infile="$filename" outfile="" opt="header,raw" mode="hl" | $text --- ..cut..
Figure 3: The new 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
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|
|11 Jan 2011||updated for CIAO 4.3: link to dax help file (information on running CIAO tools from the Analysis Menu)|
|03 Jan 2012||reviewed for CIAO 4.4: no changes|
|03 Dec 2012||Review for CIAO 4.5; no change|
|25 Nov 2013||Review for CIAO 4.6. No change.|
|16 Dec 2014||Reviewed for CIAO 4.7; no changes.|
|01 Feb 2016||Updated ds9 links.|
|23 Dec 2016||Reviewed for CIAO 4.9; no changes.|