NAME

scs - the SAXDAS Control Shell

SYNOPSIS

scs [parameter=value ...]

DESCRIPTION

scs is a simple Graphical User Interface within the SAXDAS package to facilitate the interactive analysis of SAX/LECS + MECS data. It provides a rudimentary FITS file browser, a user-friendly front-end to all SAXDAS and several FTOOL tasks, as well as a command line interface in the form of a UNIX shell running in a normal xterm. The tool does require the X11 window environment and, thus, is not usable on bare ASCII text terminals. Although, scs simplifies the interactive processing of LECS/MECS data considerably, its usage is optional - it does not contain any functionality which is essential from the data analysis point of view.

DATA FILE ORGANIZATION

scs allows a user to navigate through his/her SAX/LECS+MECS data files which could stem from, potentially, different FOTs, i.e., from different observations. It is assumed, however, that the data is organized in a particular way, viz., all files belonging to the same target are assumed to reside in the same directory, which, in turn, should exist under a common main data directory. The location of this main data directory is a parameter of scs (see datadir below). The following simple graph illustrates the directory structure that scs operates on:



<datadir> | | +-------+-------+-------+---... | | | | <trgt1> <trgt2> <trgt3> <trgt4> | | | | / \ | | | / \ ........... / \ / \ x_rev.fits y_rev.fits ...


Upon invocation, scs checks the existence of the specified main data directory, and, if this fails, a dialog box will be presented. This dialog lets the user decide whether it should be attempted to create the named directory or not. In the latter case, scs will just exit, otherwise, it will try to create the directory. If this fails, for instance due to insufficient permissions, another dialog box will appear informing the user about the failure. After that point, scs will exit.

If the main data directory was found to exist or was successfully newly created, the program will scan it for the existence of subdirectories trgt1, trgt2, etc. which have been created in a previous scs session (it will be explained later on how this is done). trgt1 is supposed to contain all files related to the celestial target trgt1, where trgt1 could be a name like Her-X1, Crab, etc.
NOTE: In this scan for subdirectories under the main data directory datadir only subdirectories previously created with scs will be recognized.
If the initial scan for subdirectories under datadir was successful, scs will initialize an internal data structure with this information and it will be possible to change into any of those found directories from within scs later on. This facilitates to work with files from different celestial sources in a single scs session.
After the initial check for the required directory structure has been successfully passed, scs will come up with a fairly large window on the screen defined in the DISPLAY variable. Please note that depending on the speed and current load of the machine it might take up to several 10s for the scs window to appear. The main scs window consists of three vertically arranged panels:

1. Command button area (upper panel)
2. Terminal window area (middle panel)
3. FITS file list browser (bottom panel)

Terminal window area (middle panel)

The middle section of the scs window comprises a "xterm" terminal window which runs the program defined in the SHELL environment variable (usually the user's prefered shell). This terminal window is linked to the other elements of the scs window in a particular way:
1. Pressing a button or selecting a menu entry in the scs window usually triggers the execution of a shell command involving a FITS file in the current source directory. This is actually carried out in the central terminal window in a way that is equivalent to typing the entire command manually. Thus, the corresponding command will be echoed and executed through the shell in the terminal window. If command history editing is enabled, the user can get this executed command back and re-issue it after potential alterations.
2. Whenever the current source or main data directory is changed, the shell in the terminal window will follow this change by doing a cd into this new directory.
3. The FITS file list browser in the bottom panel offers the option to select one or more displayed files. By pushing the F1 key while the mouse cursor is in the bottom panel, one inserts the names of all currently selected files at the actual position in the terminal window. (see below for a complete list of existing keyboard/mouse bindings for the browser panel). This feature is particularly handy in case of long file names which would otherwise have to be typed in.

Apart from these bindings, the central terminal window behaves like any other "xterm" that might run during the user's session, i.e., can be used to spawn-off any UNIX command. Its properties, e.g., background and foreground color, etc. (see man xterm) are being established in the usual way by means of an .Xdefaults file in the user's home directory. Example: It is convenient to have the "xterm" coming up with a vertical scrollbar attached to its side. This can be accomplished by adding the line:

    XTerm*scrollBar: TRUE

to the .Xdefaults file, or, alternatively, by pressing Control + middle-mouse-button in the "xterm" window and selecting the entry "Enable Scrollbar" in the then posted menu.

FITS file list area (bottom panel)

This area consists of four active elements:
1. At the bottom a large text box inside which scs displays for each FITS file in the current working directory whose name matches a specified pattern, a text row with essential information about this file. The following sample text row is broken across two lines for the sake of clarity. This is not the case in the actual file list browser window:

   005: fot_000420_LE_001_n_01_rev.fits        LE/D01 4U 1626-67   391876
   9105.6 06/08/96 14:57:07.035 24779.5 06/08/96 14:41:30.000  TTTTTT
   

   The meaning of the various fields from left to right is (an identifier in the form (KEYWORD) signifies that the corresponding information is extracted from the value of the FITS header keyword KEYWORD):
   • a running index number (three digits followed by a ":")
   • the file name
   • a two-letter instrument identifier followed by a "/" (INSTRUME)
     LE, ME, M1, M2, M3 indicate a LECS, MECS, or MECS file related to units 1, 2, or 3, respectively.
   • a single-letter main mode identifier (DATAMODE)
     D stands for Direct Mode, S for Spectrum, and I for Image Mode data
   • a two-digit sub-mode identifier (SUBMODE)
     Note: For LECS Direct Mode data this will be 01 in most of the cases.
   • the name of the source (OBJECT)
   • the number of X-ray photons in this event file (NAXIS2)
   • the total on-source time (ONTIME)
   • the UTC date and time of the arrival of the first photon (TSTART)
     
   • the totally elapsed time during the entire observation (TELAPSE)
   • the UTC date and time of the start of the observation (DATE-OBS/TIME-OBS)
     Note: This point in time does not necessarily coincide with the arrival of the first photon
   • a six-character string (letters T and F) reflecting the values of the six boolean flags: T_FLAG BABT_FLA X_FLAG Y_FLAG BL_FLAG V_FLAG

   The contents of the file list box is scrollable both horizontally and vertically through attached scrollbar widgets. In addition, the displayed files are selectable by simply clicking with the left mouse button anywhere on the corresponding text row. This will highlight the entire row and mark it as being selected. Multiple entries can be selected in this way which will then define a set of selected FITS files. Clicking on an already selected file with the left mouse button will de-select it and the corresponding text row will go back to the normal, non-highlighted state. Clicking with the middle mouse button anywhere in the file list box will de-selected all currently selected entries. Other mouse and keyword bindings exist for the file list box as well. The complete list is:

   event	action
   single click left mouse button	select/de-select file under mouse cursor
   single click middle mouse button	de-select all currently selected files
   double click left mouse button	run FTOOLS task fdump on file under mouse cursor
   double click middle mouse button	run FTOOLS task fdump on file under mouse cursor starting with second extension
   double click right mouse button	run FTOOLS task fv on file under mouse cursor
   key F1 or keys Control+F1	insert names of all currently selected files at actual position in terminal window; the list of files is sorted in ascending order of the values of the TSTART keyword.
   keys Shift+F1	same as action bound to F1 key except that, in addition, "+2" will be appended to each file name
   key F2	same as action bound to F1 key except that files are not time ordered

   
   
2. An editable field labeled "File display pattern" which is initialized to the string:

       datadir/srcdir/filepatt
   

   where datadir is the above described main data directory, srcdir is a source directory under datadir and filepatt is a file matching pattern which will usually contain wildcard characters like * and ?. datadir/srcdir always indicates the current working directory, i.e., the directory inside which all subsequent commands will be executed. The filepatt component defines the contents of the file list browser box. Changing the file display pattern for the current directory will lead to an automatic update of the contents of the file list box according to the newly specified pattern. Example: Changing /sax/data/Crab/*_rev.fits to /sax/data/Crab/*_rhk.fits followed by Return will delete the present content of the file list box and re-initialize it with all files ending in _rhk.fits in the directory /sax/data/Crab. In case the srcdir component has been changed as well, the listbox update will occur after a cd in the new source directory has been performed.
   Initial values for each of the three string components can be specified via corresponding command line parameter datadir, srcdir, and filepatt when scs is invoked.

3. A pushable button labeled "mark"
   This button is intended to be used in combination with the SAXDAS task catobs to concatenate compatible event list files. Pushing the "mark" button after one file has been selected will automatically select all files that are compatible with the manually selected one. Compatability in this context is defined in terms of equality of a set of FITS header keyword values. The set of keyword names can be specified via the keynames command line parameter.
   The "mark" button provides basically the same functionality as the SAXDAS task compevfiles: Issuing the command compevfiles x_rev.fits in the terminal window is equivalent to the sequence:
   1. Selecting file x_rev.fits in the file list box.
   2. Pushing the "mark" button
   3. Pressing the F1 key while the mouse cursor is in the file list box panel
   
   
4. A menu button which always carries the value of the filepatt component of the string in the above described entry field as label. Pushing the button will presents a pull-down menu with the following list of possible selections/actions:

   menu entry	action performed when entry is selected
   cd workdir	change back into the currently defined working directory datadir/srcdir; this is useful if the the user has manually changed the directory in the terminal window and wants to return to the initial location. Note: Manual changes of the directory in the central terminal window do not change scs's internal working directory which is always displayed in the entry field in the bottom panel.
   update	forces an update of the contents of the file list box; this is useful if a shell command has created a new file which is not yet included in the list of displayed FITS file or if a task has altered the contents of an already displayed file.
   ---------	separator
   *_rev.fits, *_lev.fits, ?_ev.fits, *_rhk.fits, *_hkp.fits, *_hkg.fits, *_spt.fits, *.rmf, *.drt, *	update the filepatt component in the file display pattern field with the selected entry and update the contents of the file list box accordingly.

   
   Example: In order to display all event list files (_rev or _lev) in the current source directory, select the entry ?_ev.fits from the menu. For information about the meaning of the pre-defined file suffixes, please consult Sect. 2.1.4 in [1] or Table 2.1 in [2].

Command button area (upper panel)

The command button area comprises all elements above the central terminal window most of which are active, i.e., are selectable. In fact the only two passive components are a static image of the SAX satellite in the upper left corner and the label field "User name" which will show the user's login name and the current host name in the form "username@host". The information is read by scs from the two environment variables LOGNAME and HOST, respectively. The other elements in the command button panel are:

Instrument button

This menu button right to the static text label "Instrument:" will post a menu with all SAX instruments as choosable entries when being pushed. Only one instrument can be active at a time which will be indicated as a text label on the button itself. Selecting a new instrument from the menu will trigger an update of the file list box in the sense that merely files from the currently selected instrument will be displayed. If no files are found an informative dialog box will be presented.

Source directory button

This is the menu button right to the static label "Source directory:". When being pushed, a menu will be posted with all accessible source directories as defined above. Selecting an entry will trigger the following actions:
1. The label of the menu button will be changed to the name of the new source directory.
2. The shell in the central terminal window will do a cd into the new source directory
3. The file list box will get updated.
The label on the menu button will always reflect the current source directory which is the component before the last one in the file display pattern field in the bottom panel. During the start-up phase of scs the menu associated with the button has been initialized with the list of accessible subdirectories under the main data directory (see above for details).

The menu button also allows to change the currently defined main data directory, which is triggered by a middle-mouse button click. In response to this event a new dialog box with a simple directory browser will appear. The usage of this browser should be intuitively clear: A double click on one directory will change into it and re-initialize the browser. Clicking on the "Ok" button will accept the current choice as the new main data directory whilst pressing the "Cancel" button will quit the dialog leaving the main data directory unchanged.

Buttons "addsrc"/"rmsrc"

By pushing one of these button one can add/remove a new/existing source directory under the main data directory. After a click on "addsrc" a dialog box will pop-up which will prompt the user for the name of the new directory. Please note that this name is interpreted relative to the current active main data directory. Specifying an absolute pathname or multi-level directory structure will result into an error or warning message respectively. An error condition will likewise be raised if the new directory does already exist. After pressing "Ok" scs attempts to create the new directory and, if this succeeds, inserts the new name in the source directory menu. The newly created entry will then become the new active source directory and the same actions are carried out as if it had been selected manually (see above). A click on "rmsrc" will bring-up a dialog which prompts the user for confirmation to delete the current source directory with all its content. If this has been answered positively, the program will actually delete the current source directory and remove it from the source directory menu. After this action, the first accessible source directory will become the active one with the above described consequences.

The Status Clock widget

This is the framed square box in the upper right corner of the main window. In there, scs will indicate the status and progress of lengthy operations, e.g. an update of the file list box, through a monotonically growing arc (like a clock) and a corresponding printed percentage value in the middle of the widget. The Status Clock widget is clickable. A click on it with the left mouse button during a file list box update will interrupt this operation leaving the file list incomplete.

Note: Almost all external SAXDAS tasks have an interface to the status clock widget as well. When run under the control of scs these tasks will indicate the status and progress of lengthy operations using the status clock as described above. Note however, that in this case, a click on the box is not effective, i.e., will NOT interrupt the running process.

The Pipeline menu

This is a menu button which when pressed posts a menu containing four entries labeled "entry stage I/II/III/IV". Each of the selections is in turn bound to another sub-menu comprising the possible choices "exit stage I/II/III/IV" with the restriction "exit stage" > "entry stage". If a selection has been made, scs will in the central terminal window spawn-off the SAXDAS task lecspipe with the currently selected file as value for the non-optional parameters firstevent and corresponding values for the entrystage and exitstage parameters respectively. Example: After the file x_rev.fits has been selected in the file list box the menu choices "entry stage I/exit stage II" will run the stages I and II of lecspipe on the file x_rev.fits.

The Quicklook menu

This button is bound to a set of cascaded sub-menus which allow a quick extraction of spectra, images and light curves from a selected event list file using appropriate FTOOLS tasks. These are fhisto in the case of spectra, fcurve for light curves, and f2dhisto for images. After the product extraction the results will be automatically displayed on the screen using the FTOOL fplot for spectra/light curves and an FITS image display program like saoimage or SAOtng for images. The following table provides an overview of the available options:

main menu entry/ type of file to extract	using FTOOL	program to display result	available sub-menus
Image	f2dhisto	saoimage/SAOtng	Spatial (RAWX-RAWY, DETX-DETY, X-Y), PHA-BL, PHA-VETO, BL-VETO
Spectrum	fhisto	fplot	Energy (PHA, PI, PIC), BL, VETO)
Rates/Light Curve	fcurve	fplot	all events, bad events


Example: After the file kv239_rev.fits has been selected in the file list box the menu choices "Image/Spatial/RAWX-RAWY" will spawn-off the FTOOL f2dhisto to accumulate a FITS image from the event list file kv239_rev.fits using the Bintable columns RAWX and RAWY. f2dhisto will write the resulting image to a new file named kv239_rawx_rawy_img.fits in the current source directory. If this is done, a chosen FITS image display program will be started to display the image.
Please take note of the following:
1. The image display program to be spawned-off for displaying FITS images can be specified via scs's command line parameter imgdisplayer. If SAOtng is available on your system, it is strongly recommended to make use of it. SAOtng has several distinct advantages over its predecessor saoimage and scs has build-in support for those new features.
2. Each command to extract a product file from an event list file is triggered by a Quicklook menu selection and the subsequent display command will be executed in the central terminal window. This enables the user to follow the entire process "by-eye" and allows him/her to easily re-issue all executed commands with possible altered parameter choices.
3. The creation of light curves offers the sub-menu choices "all events" and "bad events". The former does accumulate an event rate file considering all event data, i.e. a light-curve in the conventional sense. The "bad events" selection, does only make sense in the case of LECS data and will accumulate a rates file taking only special corner pixels into account. This special light curve will provide information about the "quality" of the observation which, however, will only be interpretable by members of the SAX/LECS hardware group team. The general observer is discouraged from using this option.



The Fselect front-end button

This is a simple button which when pushed will bring-up a fairly large dialog box representing a graphical-front end to interactively construct a boolean expression for the FTOOLS task fselect. Prior to interact with this dialog, an event list file has to be selected. After a boolean expression has been defined, the FTOOL task fselect will be run on this file creating a new event list file in which those events have been "filtered out" for which the specified boolean expression is false. For more details on this, please consult the fselect documentation. The name of the output event list file will be automatically derived from the input file name by inserting the string sel1 before the type extension _rev.fits or _lev.fits respectively. In case of a name conflict with an already existing file scs will "advance" the name suffix to sel2, sel3, sel4, etc. until the conflict is resolved.

Before fselect is actually run on the original event list file the user will be given the opportunity to alter the command line parameters including the automatically generated name of the output file. This will make use of the general FTOOLS task front-end xft which is part of the SAXDAS software package. For more information about xft please follow the indicated link.

The dialog box to construct the boolean expression for fselect is very intuitive. It allows the user to build-up a complex filtering expression involving spatial region definitions or interval specifications in time, PHA, VETO, or BL space. A valid expression would be for instance

    (PHA>=30&&PHA<=570)&&(BL>=20&&BL<=80)

which selects events with PHA values in the range 30 to 570 and BL values between 20 and 80. For the meaning of the column names in event list file like PHA or BL, please consult Chap. 2 in Ref. [1].
The following table gives an overview of the available options to make spatial region selections:

button text	type of spatial region definition
SAOtng region	This reads a region definition file created by the FITS image displayer SAOtng if this is available on the system. If this button is pushed, scs will accumulate an image from the selected event list file and display this image in SAOtng. At this point the user is supposed to make a region selection in the SAOtng window (please refer to the SAOtng documentation on how to do this) and, if this is done, re-press the SAOtng button in the Fselect dialog box. This will then read the performed region definition from SAOtng and construct a corresponding boolean expression which will finally be inserted in the entry widget at the top of the dialog box.
circle	a circle; position and radius in raw pixels coordinates can be specified through the entry widgets labeled "center X", "center Y", and "radius" respectively.
rect. box	a rectangular region defined by a center point, X/Y half-widths and a rotation angle; the relevant entry widgets are labeled "center X", "center Y", "half X", "half Y", and "rotation angle" respectively.
ellipse	an elliptical region defined by the same quantities as the rectangular region
Cal-Src I/Cal-Src II	a rectangular region definition selecting the events from the calibration sources number I/II
FOV	circular region defining the Field-Of-View
BG box	a rectangle outside the FOV and away from either of the two calibration sources

The Xselect front-end button

This simple button brings up a dialog box which represents a front-end to extract a spectrum and/or light-curve and/or image from a selected linearized event list file (type _lev) using the FTOOL Xselect. The dialog allows to control the following parameters of the extraction process:

type of parameter	element in dialog
Which type of product file shall be extracted?	selectable check buttons
Names of output files	editable entry fields with default values based on the name of the input event list file
phaname, xyname, wmapname	multi-entry menu buttons; for the meaning of the three parameters, please consult the Xselect documentation
Circular region definition for spatial filtering in Xselect	entry widget labeled "center X", "center Y", and "radius" defining the position and radius of the circle in raw pixel coordinates
Type of post-processing to be performed on extracted spectra	two selectable check buttons labeled "updttime" and "grppha"




The FTOOLS menu button

This button is bound to a menu comprising the entries "general", "time", "Xronos", and "SAX specific". Each of those items is connected to another menu which represents all available FTOOL tasks in the respective category. Making a particular selection will run the corresponding task using the FTOOLS front-end xft which allows the user to interactively alter the task parameters prior to execution. The selection of an entry in the FTOOLS menu requires one or more event list files to be selected which will then form the value of any required input file parameter (if applicable).

The Help button

When being pushed, this simple button will launch the WWW browser program specified through the parameter wwwbrowser which will be pointed to the URL given by the parameter helpurl.

The Quit button

Pushing this button will end the current scs session. Please note that the user will not be prompted for confirmation of this action.

PARAMETERS

The following command line parameters are recognized by the program:

shellrows = 24 [integer: 10-30]

The number of text rows of the central terminal window.



shellcols = 80 [integer: 60-120]

The number of text columns of the terminal window



shellfont = "10x20" [string]

The font for displaying text in the terminal window. The standard syntax for specifying X11 font names (including wildcards) is accepted.



shellfgcol = "black" [string]

The foreground color of the terminal window - must be a valid X11 color name.



shellbgcol = "white" [string]

The background color of the terminal window - must be a valid X11 color name.



wwwbrowser = "netscape" [string]

The name of a WWW browser to be spawned when requesting help via the help button.



helpurl = "http://astro.estec.esa.nl/Sax/Sax/Saxint/saxmain.html" [string]

The URL for help on SAXDAS issues.



imgdisplayer = "saoimage" [string]

Name of a program capable of displaying FITS images created by the FTOOL task f2dhisto. This program will be spawned by any Quicklook/Spatial menu selection.



pgplotdev = "/xwin" [string]

The default PGPlot device - will be passed to FTOOL fplot.



filelistrows = 12 [integer: 5-40]

Number of displayed rows in the FITS file list window



filelistfont = "-adobe-courier-bold-r-normal--12-*" [string]

Name of font for displaying entries in the FITS file list window - the standard X11 font name syntax is accepted.



datadir = "$env(HOME)/datsax" [string]

The name of the primary data directory to be used. datadir can comprise names of environment variables in Tcl-syntax, i.e., $env(...) where ... is the name of an existing environment variable. If the specified directory does not exists, scs will attempt to create it.



srcdir = "." [valid directory name]

This must be the name of an already existing subdirectory under the main data directory, i.e., a source directory. scs will change into the specified srcdir upon invocation. The special value "." means to use the first entry found by the automatic scanning process described above. This will also be utilized if the specified srcdir does not exist.



filepatt = "*_rev.fits" [string]

A regular expression (Tcl syntax). All files matching datadir/srcdir/filepatt will be displayed in the FITS file list panel.



instrument = "LECS" [LECS|MECS|MECS{1,2,3}|HPGSPC|PDS|WFC1|WFC2]

Name of the default instrument - only files corresponding to instrument will be displayed in the FITS file list box.



keynames = "EXTNAME DATAMODE SUBMODE OBJECT GUPOW HVPOW AEPOW CELLON PMTON CELLHV PMTHV HANDLER DM_CONT" [string]

A blank separated list of FITS header keyword names. Two FITS event files are regarded as being suitable for concatenation if the values of each of those keywords match.



help = no [boolean: yes|no]

If set to yes, the program displays a brief on-screen description of all available command line parameters together with the current program version number and exits successfully.

EXAMPLES

1. Start scs with /sax/data as the primary data directory:

       scs datadir=/sax/data
   

2. Start scs with /sax/data as the primary data directory and Cyg-X1 as the default source directory. The number of rows in the file list panel shall be 18:

       scs datadir=/sax/data srcdir=Cyg-X1 filelistrows=18
   

FURTHER DOCUMENTATION

1. The SAX LECS Data Analysis System - Software User Manual,
   U. Lammers, Doc. SAX/LEDA/0010
2. A guide to SAX/LECS data analysis,
   F. Favata, Doc. SAX/LEDA/0017

BUGS

None known.

SEE ALSO

catobs, compevfiles, xft, SAOimage/SAOtng documentation, FTOOLS documentation for various tasks (fdump, fhisto, f2dhisto, fselect, Xselect, etc.)