MUSR GUI USER'S MANUAL

• Make sure you are working in a browser that can support MUSR GUI Applet:

  Netscape:  4.77 (Linux)
             7.02 (Linux i686, X11) - Mozilla/5.0 - java 1.4.1 plugin;
             7.02 (Mac OS X) - Mozilla/5.0 - java 1.3.1 plugin;

Safari:    1.0 (Mac OS X) - java 1.4.1 plugin;   (GUI not optimized)

• You need to copy the .java.policy file into a speciffic place on your computer:
  

  Platform	Where to save the .java.policy file
  Unix	/home/<userid>/.java.policy   (home directory of your computer)
  Mac OS X	/Users/<userid>/.java.policy   place the file in your home directory. MAC OSX has a Unix-like user home directories.  One way to do this is to open a terminal window, which runs the Unix-like tcsh shell. This starts you in your home directory. Then you can edit (with vi, or another text editor) the .java.policy file and cut and paste the above contents into it.
  Windows 95/98 (single-user)	C:\WINDOWS\java.policy
  Windows 95 (multi-user)	C:\Windows\Profiles\<userid>\java.policy
  Windows NT (multi-user)	C:\Winnt\Profiles\<userid>\java.policy

  
  This File is also included with the downloadable musrPackage (see below for more details)
    Note that when you are saving the .java.policy file as a text file, some operating systems may append a .txt extension. If this happens, you must rename the file and remove the extension.
  Notes For Windows
•   In the various Windows operating systems, there is a setting which can hides the file extension. Go to the "Folder Options" settings, and make sure the box labeled "Hide file extensions for known file types" is NOT checked. You can get to the "Folder Options" from the Windows Explorer "View" menu on Windows 98, or the "Tools" menu on Windows NT and 2000.
• If you do all of the above and the "Save As" buttons still do not become active, there is one more thing you can try. You can tell the Java Plug-in exactly where the .java.policy file is by doing the following:
       1.    Open the Java Plug-in Control Panel and find the entry box for "Java Runtime Parameters."
                      (See step 1. in the plugin memory boost page for how to get to the Plug-in Control Panel.)
       2.    In the area where you can enter "Java Runtime Parameters", you can put the following statement:
                            -Djava.security.policy=C:\WINDOWS\.java.policy
              This assumes that you put the .java.policy file in C:\WINDOWS.
  

When the GUI is loaded, it will automatically search for a 'default.gui' file in the /tmp/ directory that is universal to most operating systems.
This is a file that contains the previous GUI state (see 'Save GUI' menu option) and it is loaded for convenience so that the user can continue
to work without having to load a saved state. If the 'defalult.gui' file is not there, it will just report that the file wasn't found and a default
GUI state will be loaded to start work from scratch or load some other GUI state.

    Status text field for any message display

Is located below of the GUI menu-bar and is used to display any information, comment or error that the GUI would want to inform the user of.

MENU OPTIONS:

   File

 
• Open a Saved GUI- (Ctrl+O)
This option opens a GUI state that had previosly been created by using the 'Save GUI' menu option.
If there is a Diplay Plots Frame open while loading the GUI state, the new plot will automatically be loaded into it.
The fiel is zipped so the loading process unzips the file.


• Save GUI - (Ctrl+S)
This option will save the current GUI state. The files can be saved with a '.gui' extension to distinguish the files easier.
The file is zipped before it is saved into a directory.
Note: when the 'save window' comes up, it will have a filename 'default.gui' written in it. If the user saves the state under this name, then,
that state will be automatically loaded the next time GUI is started up. It is important to save this 'default.gui' file in the same directory
netscape or IE (i.e. GUI) is loaded from (this is mainly for the UNIX users that run their netscape application from their xterm windows).


• Import Data Table from File on 'musr.triumf.ca' Server (through RMI)

• Import Data Table from File on 'cmms.triumf.ca' Server (through RMI)

• Import Data Table from local file - (Ctrl+I)
This option will load in the selected .'db' file. The file has to be a standard db file.
It also loads '.' files.
The .java.policy file that you have in your home directory should allow you to load db files from anywhere in your computer.


• Remove Data Table - (Ctrl+R)
This option removes the Data Table that is selected in the Data Tables Panel.
 
• Quit - (Ctrl+Q)
Exit the GUI.

• Display Plot - (Ctrl+D)

This option will display the plot based on all the set-ups that were done in the GUI regarding plots.
The plot is displayed in a separate window. It contains within itself:
    - Back button:
    - Refresh Button:
There is a Zoom option if the user wants to zoom in. Just simply select a square area to zoom in. The Back Button is used to go back to the previos views of the plot.
If for some reason the plot doesn't 'look right', the refresh button will l oad everything from scratch.
 
• Main GUI Window (DataTables and Columns) - (Ctrl+G)

 Data Tables panel:
            Every db file that is loaded is listed in this panel. One Data Table corresponds to one db file.
 Remove DataTable button
            This button removes the selected DataTable. Note: this doesn't remove the plots selected in x-axis and y-axis panels.
Columns panel
            These are all the columns that are contained within the selected Data Table in the Data Tables Panel.
 View Coulmn Data
                    This button will display the data of teh selected column in a separate persistent window.
  x-axis panel
               By selecting any column in the Columns Panel and by pressing the add X button, that column is added to this panel.
               Dependeng on the which Data Table is used in the Data Tables Panel, an appropriate number that corresponds to that Data Table will be added in brackets after the column name.
               This column will be a part of the selected Frame. One can add as many x-axis columns as one wishes.
  y-axis panel
                By selecting any column in the Columns Panel and by pressing the add Y button, that that column is added to this panel.
                This column matches with the selected x-axis column. Therefore it is not possible to choose a y-axis column unless that column is from the same Data Table as the selected x-axis column.
                One can add ass many y-axis columns with some x-axis column as one wishes.
 add X button
                This button adds the selected column from The Columns Panel into the x-axis Panel.
 remove X button
                This button removes the selected x-axis column from the x-axis panel. It also removes all the y-axis columns associated with this x-axis column.
 add Y button
                  This button adds the selected column from The Columns Panel into the y-axis Panel.
 remove Y button
                    This button removes the selected y-axis column from the y-axis panel.
 Display Plot
                    This option will display the plot . To see details about it, look up the 'Display Plot' Menu option.
• Show Title, Abstract, Comments
       Will open a new window and display the selected Table's Title, Abstract and Comments.
        -Abstract: A db file that is loaded usually has an Abstract within itself with comments about the experiment and data.
        -Comments: In the db file, every row of the data that is loaded into datacolumns can have a comment about it at the end of the line.


• Data Spreadsheet- (Ctrl+E)
This is the spreadsheet that contains all the data that was loaded from the db file.
 
• Functions Table
This displays all the functions defined (with the Tools/Define Function option) and default in the GUI.


• Constants Table
This displays all the constants defined and default in the GUI. THere three ways that constants are put into the table.
One: it is defined by default,
two: when the user defines it from the Tools/Define Constant option
and three: when the db file is loaded any constant definition in the data that is loaded is recorded in this table.

 
• Axis Types
-The x or y axis can be displayed in three different ways, as linear, logarithmic or inverse.


• Point Type s & Sizes
Set  Graph Type:
-The graph can have the data points be connected with a line.
-The actual data points can be changed into different symbols. Onceone of the symbols is chosen, the 'line' checkbox is
    automatically disabled but can be turned back on if the user wishes to have both the symbol points and connected points with a line.
Set Symbol Size:
- This option changes the sizes of the symbols that are chosen for the data points in the graph.
Set Graph Color:
- This option sets the colour of the graph line and symbols.


• Title and Labels
-in case the user desides to have his/er own Title and Labels in the plot, these settings will override the default Title and Labels.


• Limits (Min and Max)
-the GUI makes automatic calculations to display the plot the best way it can to arrange all the data be nicely seen.
-the user can wish to make his/er own graph min-max limits settings. If the text field for either x, y min or max have values in them, the GUI will not make automatic arrangements for that 'part' of the axis. If the textfields are blank, the GUI will calculate that end-point of the axis automatically.


• Strict Limits
This option lets teh user choose the way the plot's azis are diplayed in terms of limiting values on the labels.
If the Strict Limits are ON, then the GUI will take EXACT min and max values for the axes end-points (So called - tight labels).
If the Strict Limits are OFF, then the GUI will automatically make a nice looking axis based on the limiting min and max values (So called - loose labels).
The min and max values can be:
    - the smallest and largest data point value of overall data that is in the graph (if the Limits (Min & Max) textfields are empty) , or
    - the min and max values in the Limits (Min and Max) menu settings if the user had put a value in any one of the four textfields.


• Set case-sensitive
If this option is ON, all the Constants and Functions that are defined will be case-sensitive, i.e. it WILL matter if a value is defined as upper or lower case.
If this option is OFF, all the Function and Constant values will be defined as upper case.
 
• Color Options:
    - Background Color - sets the background color of the plot.
    - Borderline Color - sets the colors of teh border lines in the plot, including the title and the labels.


• Label Font :
    - Label Font Type - sets the font type for the numbers and labels around the plot
    - Label Font Style - sets the font style for the numbers and labels around the plot
    - Label Font Size - sets the font size for the numbers and labels around the plot


• TitleFont :
    - Title Font Type - sets the font type for the title above the plot
    - Title Font Style - sets the font style for the title above the plot
    - Title Font Size - sets the font size for the title above the plot


• NumbersFont :
    - Numbers Font Type - sets the font type for the axis numbers
   - Numbers Font Style - sets the font style for the axis numbers
    - Numbers Font Size - sets the font size for the axis numbers


• Plot Setup (pix):
    - Top Distance - sets the distance in pixels from the edge of the window to the borderline of the plot
    - Bottom Distance
    - Left Distance
    - Right Distance


• Graph Setup:
    - Error Bars - can be shown or hidden in the plot.
    - Error Bar Edge Tics - can be on or off.
    - Dot Fiducials - are the dots displayed within the plot at prominent tic spots, to make the graph look more structured. Can be on or off.


• Zero Axes Setup:
    - Horizontal - adds a dotted horizontal line, where x value is zero.
   - Vertical - adds a dotted vertical line, where y value is zero.
 
• Status Info:
- This list shows the values of various variables that can be changed in the "Options" menu.

Tools
 

• Command Line Console

This feature enables the user to enter one's own commands directly into the GUI.

For more detail, you can view the DB Commands at dbonly.html.  For the full DB documentation, refer to db.html.
    Note: db.html documentation includes the DOPLOT Commands as well, however, these have not been implemented in the Java MUsr GUI.
   Note: If you have loaded the musrPackage, these files can also be found in the musrPackage/html/ directory.

    There are slight differences in the way they were implemented in GUI so I'll give some explanations about them below.
Note that in the Data Table panel, there is a 'default' Data Table that is always there. This Datatable is used to load the data into from the command line input console.
All the commands called in the console are by default applied to whatever is loaded in this default Data Table, since that is the one that will be selected in the
Main GUI Window. However, if the user selects any other data table in teh Main GUI Window, the console commands will be applied to that Data Table.
    If the user wants, it is possible to save the default DataTable state into a new DataTable that is also placed in the DataTable Panel (see command SAVE below).
Also note that as the commands are called from the console, any changes that are made can simultaneously be observed in the GUI.

These are the COMMANDS that have so far been implemented and that can be called from the console:


• @filename
-this loads a file.
Note: it is important to load the file with a full path name given.
The path name starts from the directory netscape (or IE) was loaded in (in the case it was loaded in UNIX, but not in Mac or Windows).
If it is a .db file, it is loaded into the 'default' DataTable, identically as the way it is loaded by calling the 'Import Data Table from a Local File' menu option.

-if it is a command file (i.e. filename.), it will read it and handle the:
                PLOT, CONDITIONAL PLOT and ZERO commands within it and the @filename command too.
    example (loads a file filename, extracts columns A and B based on the condition, chooses the point type and then zeroes the data table:
        @filename
        plot A B if T>0
        0
        zero
        yes

• ABSTRACT
- Loads the abstract into the 'default' DataTable.
• COMMENTS
- Loads any comments into the 'default' DataTable
• COMMENTS
- Loads any comments into the 'default' DataTable
• DATA
- Allows data input into the columns.
Note: in the old DB, when there would be some mistake in data input, the DB would ask the user to enter all the data points manualy. Here, it just leaves the DATA
    command and goes back to the 'DB:' prompt.
• EXIT
- Simply 'hides' the Command Input Console. To re-open it, choose it from the menu again.
• GENERATE
- Generates a new column based on the given expression.
Note: if the this command is called when there is no data, it will aks for number of rows and for an expression, however, it will not create a 'reference' column
    called I, the way DB used to.
• LABEL
- This command can be called before or after DATA has been called. It allows the user ot give labels to the loaded columns.
• MODIFY
- Modify will modify a given column based on the expression that was supplied.
• PLOT
-Handles two types of plotting: regular PLOT command and the CONDITIONAL PLOT command. See link above for details.
The CONDITIONAL PLOT can take in at most two conditions. If there are two conditions, they have to be separated with a logic symbol: & or |.
A condition can be:
-An expression. In this case, the expression is compared to be larger than zero. It can contain a reference to any number of existing columns. (ex. T, T+3, cos(T)..)
-Two expressions separted by <,> or = (not <= or =>). Each of the two expressions can contain a reference to any number of existing column names. (ex. T>3, T=100, T+3<cos(T)...)
-Once the plot caommand is entered, the console will ask the user to put in a point type. These are the numbers that are associated with  a certain point. If any other
    number is used, the point type will be assigned automatticaly to some type.
        -1: dot; 0: square; 1: circle; 2: triangle; 3: nabla; 4: diamond; 5: star;
        20: squares connected; 21: circles connected; 22: triangles connected; ..
• SHOW
-shows Data, Labels, Abstract, Comments or Title.
• TITLE
-Loads a title into the 'defult' DataTable
• ZERO
- empties the 'default' DataTable. After this it can be loaded again from scratch.
• SAVE
- saves the state of the 'default' DataTable into a new DataTable under a new name and places it into the DataTable Panel in the GUI.



• Frames

    The add button creates a new Frame which is a completely new plot for the new columns that are to be added.
    The remove button removes the selected Frame and all the x- and y-zaxis columns in it.
    If the checkbox is set to auto, the Frames are automatically arranged.
    If teh checkbox is set to manual, then it is possible to arrange the frames in the window that is displayed.
    It is possible to have a Frame not be displayed with other frames by dissableing the visible checkbox.
    the x<->y checkbox will invert the plot. (i.e. it will display the x axis as y and the y axis as x.)
 
• Define Function

The gui provides a feature for the user to define a 'custom' function. This function can then be used in the db file that is loaded.
The function takes only one parameter which has to be called x.


• Define Constant

When the constant is defined, it is put into the Constants table. Then the db file that is being loaded can use this value. The constants are usually defined with upper-case letters.
 
• Automatic Symbol Size Setup

This whole feature was added so that the user doesn't have to worry too much about setting different symbol sizes in the graph everytime a new column of data is added.
Since for a column that hase many points, the symbols would be prefered to be bigger and vice-versa, a simple algorithm takes care of that when the column is added.
This menu option allows the user to change the parameters of that algorithm to allow different symbol size settings when new data column is loaded.
This is the algorithm: size = (0.5)*nPix/max(N,Nmax), where nPix 'simulates' the plot width in pixels, Nmax represents the smallest number of data points that
    will be used in the algorithm. N is the number of data points. nPix and Nmax are the parameters that the user can change.
Note: The symbol sizes of each individual sets of data can always be changed to a new setting in the Plot Options menu.
 
• Plot Size Setup

Enables the user to choose the size of the Plot That will be printed out (on to paper or to a file).
For Portrait mode, the user can manually set the sizes of the plot axes in centimeters. The default settings are 15x12 cm.  For Lanscape (and Reverse Landscape) mode, the default settings are 15x20 cm. If the user sets the values to be bigger than these, GUI will automatically print them with the deafult  setting since these settings are the largest possible setitngs that can fit on a A4 format plot.
 Note: this was 'calibrated' with GhostView page formats!


• Print - (Ctrl+P)

There is an option to print to a file or to a printer.
If printed onto a file, the printout format in linux is .ps which can be viewed with a GhostViewer. In Mac OS X, the default printout format is .pdf.
At this time,  GUI doesn't support any other printing format.
(Note to Mac OS X users: the Landscape option doesn't work properly since the Netscape doesn't do the rotation of the plot properly, use: Portrait option).

Note:
- To make additional settings, choose the 'PrintSetup' menu item.
-The print option will print everything that is contained within the display Frame, if there are more than one plots within the frame and the user wants to print out only
    one of them without having to erase the rest, there is an option 'hide' in the GUI where the rest of the plots can be put into so that only one plot is displayed and can
    then be printed out.