A User’s Guide to FAS

 

 

 

Fusion Analysis Software

 

 

Version 3.1.1 (5/99)

 

 

Contents

1. Introduction *

1.1 Overview *

1.1.1 Contents of this manual *

1.1.2 Introduction to FAS *

1.1.3 What can FAS do? *

1.2 Getting Started *

1.2.1 Set-up on VMS *

1.2.1.1 X-window Output *

1.2.1.2 Logicals *

1.2.2 Set-up on UNIX *

1.2.2.1 X-window Output *

1.2.2.2 Logicals *

1.3 Running the graphical interface version of FAS *

1.4 Window, Panel, Trace, Element - FAS Terminology *

2. FAS X-windows graphical environment *

2.1 Navigating within FAS *

2.1.1 Window *

2.1.2 Print *

2.1.3 Zoom *

2.1.4 Page *

2.1.5 Data I/O *

2.1.6 Process *

2.1.7 Plot Options *

2.2 Reading in data *

2.2.1 Shot List *

2.2.2 Signal Selection List *

2.2.3 Signal Read List *

2.2.4 Read Data *

2.2.5 Saving shot and signal lists *

2.2.6 Getting shot and signal lists *

2.2.7 The Read Special button *

2.2.8 Experiment (CURRENTLY DISABLED) *

2.3 Deleting channels from memory *

2.4 Plotting data *

2.4.1 Plot style *

2.4.1.1 Panel *

2.4.1.2 Overlay *

2.4.1.3 Custom *

2.4.2 Panel margins *

2.4.2.1 None *

2.4.2.2 Auto *

2.4.2.3 Manual *

2.4.3 Xrange *

2.4.3.1 Universal *

2.4.3.2 Sequential *

2.4.3.3 Manual *

2.4.4 Yrange *

2.4.4.1 Individual *

2.4.4.2 Universal *

2.4.4.3 Manual *

2.5 Zooming *

2.6 Customizing plots *

2.6.1 Changing Settings *

2.6.1.1 Individual, Panel and Window Settings *

2.6.2 X and Y axis *

2.6.3 X and Y ticks *

2.6.4 Color *

2.6.5 Style *

2.6.6 Smoothing *

2.6.7 Symbol *

2.7 Creating a page *

2.8 Printing *

2.8.1 Processing Window *

2.8.1.1 Channels in memory *

2.8.1.2 Channels to process *

2.8.1.3 Display Channels *

2.8.1.4 Filter *

2.8.1.5 Select All *

2.8.1.6 Clear list *

2.8.2 Integrate *

2.8.2.1 Selecting the time range *

2.8.3 Polynomial *

2.8.3.1 Data I/O *

2.8.3.2 Inputs *

2.8.3.3 Easy Options *

2.8.4 Spectral *

2.8.4.1 Setting the time range *

2.8.4.2 ‘Output’ Options *

2.8.4.3 ‘Window’ options *

2.8.4.4 ‘Reference channel:’ *

2.8.4.5 Zero cross function *

3. FAS Macros *

3.1 Introduction *

3.2 Macro Environment *

3.2.1 Basics *

3.2.2 Macro window in FAS *

3.2.3 Using Macros from the IDL command line *

3.2.4 Switching between the FAS window and command line modes *

3.2.5 Debugging and recompiling macros *

3.3 FAS Internals *

3.4 Organization of routines *

3.4.1 General FAS routines *

3.4.2 Calculation *

3.4.3 Data Access *

3.4.4 Plotting *

3.4.5 Printing *

3.4.6 Rules *

3.4.7 Hints *

3.5 Examples *

3.5.1 Plotting Channels *

3.5.2 Changing the plot options *

3.6 Commonly used FAS functions. *

3.6.1 FAS_DATA *

3.6.2 LASTCHAN *

3.6.3 LASTSHOT *

3.6.4 FAS_NAME *

3.6.5 FAS_NPTS *

3.6.6 FAS_SHOT *

3.6.7 FAS_STRUCT *

3.6.8 FAS_TIME *

3.7 Reference for user routines *

3.7.1 General Points *

3.7.2 FAS_0CRS *

3.7.3 FAS_CRSP *

3.7.4 FAS_DELC *

3.7.5 FAS_FFT *

3.7.6 FAS_INTG *

3.7.7 FAS_LIST *

3.7.8 FAS_MODIFY_CHAN *

3.7.9 FAS_PLOT_OPTIONS *

3.7.10 FAS_POLYNOMIAL *

3.7.11 FAS_PRINT *

3.7.12 FAS_READ *

3.7.13 FAS_READ_FILE *

3.7.14 FAS_SETUP *

3.7.15 FAS_WINDOW *

3.7.16 FAS_WRITE *

 

 

 

 

  1. Introduction

    1. Overview

      1. Contents of this manual

        2.

        This manual provides detailed instructions for using FAS in all modes.

      2. Introduction to FAS

        3. FAS (Fusion Analysis Software) is a combination graphical user interface(GUI), command line and macro language based program created using IDL for analysis of MDSplus data.

      3. What can FAS do?

        4. FAS can read from and write data to MDSplus. It can be used to plot, overlay, process and print data from individual shots or multiple shots. With the use of macros FAS can perform any IDL function directly. A hard copy of anything displayed using FAS can be obtained easily.
    2. Getting Started

      3. FAS runs on VMS and Unix systems that have IDL licenses. FAS setup is different on VMS and Unix. There are additional, optional logical names/environmental variables which allows you to customize your operation of FAS. If you are not already an IDL user, see http://NSTX.pppl.gov/nstx/Software/IDL/setupidl.html .

      FAS is designed to work on monitors with 8-bit color (256 colors) and at least 1024x780 screen . FAS will use only 32 colors, so other applications will not have to use a private color map.

      1. Set-up on VMS

        2. On the PPPL VMS cluster (these should go in your login.com file):

              $ SETUP IDL X
        

              $ SETUP NSTX 		!if you want to access NSTX data
        

              $ SETUP FAS

        1. X-window Output

          2. The FAS ‘widget’ interface will only run on a terminal that has X-windows capabilities. Your VMS "display" must be set to your terminal’s TCP/IP address. If the "Node" indicated when you type SHOW DISPLAY at the DCL prompt is not your terminal, or you receive a "Is your DEVICE environment variable set correctly?" message from IDL, then you must set it. This can be done on VMS using the command:

                $ set_display <node_name>

          Where <node_name> (without the angle brackets) is the name or TCP/IP number of your terminal (e.g. CTEKA or 198.35.3.11,)

        2. Logicals

          3. Certain optional logicals can be defined for FAS. To override the defaults put the following commands into your login.com file.

                $ DEFINE GRF <Graphics Location>

          Where <Graphics Location> is the directory to which FAS writes graphics files (named FASV3_0.PS;1 for version 3 of FAS) when printing. The user must have write access to this directory. The default is the user’s login directory.

                $ DEFINE fas_dir  <FAS directory>

          Where <FAS directory> is the directory containing the FAS source files, files for valid printers, logos, etc. 

                $ DEFINE machine nstx

          Where "nstx" can be another machine.

           

      2. Set-up on UNIX

        3. On the PPPL Unix Cluster (in the c shell):

             source /nstxusr1/util/setup/setup_nstx.csh

        1. X-window Output

          2. The FAS ‘widget’ interface will only run on a terminal that has X-windows capabilities. Your DISPLAY environmental variable must be set to your terminal’s TCP/IP address. If the "Node" indicated when you type echo $DISPLAY at the system prompt is not your terminal, or you receive a "Is your DEVICE environment variable set correctly?" message from IDL, you must set it. This can be done in the c-shell using the command:

          setenv   DISPLAY <node_name>:0

          Where <node_name> (without the angle brackets) is the name or TCP/IP number of your terminal (e.g. CTEKA or 198.35.3.11).

        2. Logicals

          3. Certain optional logicals can be defined for FAS. To override the defaults put the following commands into your .cshrc file.

          setenv GRF <Graphics Location>

          Where <Graphics Location> is the directory to which FAS writes graphics files (named FASV3_0.PS for version 3 of FAS) when printing. The user must have write access to this directory. The default is the user’s login directory.

          setenv fas_dir  <FAS directory>

          Where <FAS directory> is the directory containing the FAS source files, files for valid printers, logos, etc. 

          setenv MACHINE NSTX

          Where NSTX (the default) can be another machine.

           

    3. Running the graphical interface version of FAS

      4. To start, enter IDL and type fas, or simply type fas at the system prompt. The NSTX logo will appear while FAS loads and then the screen should look like:

      The first window that appears on FAS is the Data I/O panel, this is because before any of the other functions can be used data must first be read in. Click on return to go to the main FAS window:

    4. Window, Panel, Trace, Element - FAS Terminology

      5. A window is the output area reserved for the plots created within FAS. There are 10 different windows which can be used.

      A panel is a designated area within a window. The width of the panels does not change (unless the margins are altered; see section 2.6.2), and the height of a panel is dependent on how many panels are in use in that given window, i.e. the height of the panel is the total height (less the top and bottom margins) of the window divided by the number of panels in use. Each window can contain up to 10 panels.

      A trace is a single graph, which is assigned to a particular panel.

      An element is an index to the current trace within a window. Each panel can contain up to 10 Traces (so each Window can have up to 100 Traces).

      For example if in Window 1 there are 3 panels in use and there are 2 Traces in Panel 1, 3 Traces in Panel 2 and 1 Trace in Panel 3, there would be a total of 6 Elements. Element 4 would be Trace 2 in Panel 2, and Element 7 would not exist (in Window 1).

       

  2. FAS X-windows graphical environment

    1. Navigating within FAS

      2.

      In the main window the main control panel is active of the following box is not grayed-out.

       

      1. Window

        2. This button brings up the window panel. Channels to be plotted can be selected here. The plotting style can be selected (e.g. As a panel or overlaid), the type of ranges to use can also be selected.

      2. Print

        3. This button brings up the print panel which lets you print any of 10 windows. Various printer queues may be selected, or you may simply create a postscript file.

      3. Zoom

        4. This button brings up the zoom panel which allows the user to zoom using a point and click interface. At present only the x-zoom works.

      4. Page

        5. This button brings up the page panel which is similar to a desktop publisher. Windows that have been created are put into cells that can be modified or moved. Using cells and windows the desired page layout can be produced. In this way up to ten pages can be produced each with up to 10 windows.

      5. Data I/O

        6. This button brings up the Data I/O panel ( the first panel that is displayed when FAS is started). Before using any of the other options data must first be read in using the Data I/O panel (or a macro). This panel has many versatile functions. Shot numbers and signal can be filtered and displayed for click-selection. Shot numbers and signal names may also be read from files. Up to 999 signals can be accessed at any one time but due to memory limitations a maximum of 300 is recommended.

      6. Process

        7. This button brings up the process window for selecting. The user can perform calculations on the selected channels using the processing routines (see section 3.4.2).

      7. Plot Options

      This option lets the user manipulate the graph. For example, the color of a trace or its thickness, etc., can be changed. Even the scale or the number of ticks on the axis can be changed.

    2. Reading in data

      3. From the main window click on the Data I/O button to bring up the Read Graphical Interface panel. There are three lists towards the bottom of the screen called ‘Read these Shots:’, ‘Signals Contained In Shot <SHOT NUMBER>’ and ‘Read these Signals for each Shot:’.

      1. Shot List

        2. The ‘Read these Shots’ list displays the shot numbers which have been selected. Shots can be selected EITHER by entering the shot number in the ' Shot Number:' box and pressing Return (or Enter) on your keyboard, OR by getting a saved list by clicking on the ‘Get Shot List’ button. Alternatively, a quick and easy way of getting the most recent shot number is by clicking on the ‘Get Most Recent Shot Number’ button. A series of shots can be specified can typing an integer into the ‘To:’ box. The first shot in the sequence being denoted by the shot currently in the ‘Shot Number:’ box.

      2. Signal Selection List

        3. The ‘Signals Contained In Shot <SHOT NUMBER>‘ list displays the signals contained in the shot number displayed in the heading, this list can be manipulated using the filter function. To list all the signals associated with the shot (in the ‘Shot to filter:’ box) clear the filter box and click on filter. Required signals can be filtered out by using wild cards * and ?:

        * - Use for a group of characters

        ? - Use for a single character

        Examples:

        To filter out all signals with OH anywhere in the signal name, type *OH* in the filter box and click on Filter.

        To filter out all signals starting with VS and which have four following characters, type VS???? in the box and click on Filter.

      3. Signal Read List

        4. The ‘Read these Signals for each Shot’ list displays all the signals that have been selected for reading. To select a signal, simply click on it in ‘Signals Contained In Shot <SHOT NUMBER>‘. To deselect a signal, click on it in this list. Signals can also be selected by clicking on the 'Get Signal List' button (this is the recommended way to select signals). Another way to select a signal would be to type it into the 'Signal Name:' box and press Return (or Enter) on your keyboard.

      4. Read Data

        5. When all this is done the data can be read in by clicking on the (big) Read Data button.

      5. Saving shot and signal lists

        6. The most commonly used shots and/or signals can be saved in files to be read in later. Getting commonly-accessed signal names from a file is strongly recommended. To create such files, click the appropriate button buttons. If the ‘Save Shot List’ or the ‘Save Signal List’ buttons are clicked the following window comes up:

        Specify the name of the file by typing it into the ‘Selection:’ box; there is no need to type in the extension. If the extension is specified it is deleted and the appropriate extension is added ( .SHL or .SGL ). Specify the directory in which to save the file by clicking once on the subdirectories in the ‘Subdirectories’ list. To go up one directory level click on "-" for VMS and ".." for Unix. Click on the ‘Write’ button to write the shot or signal list.

        [Note: When saving a signal list the default file name is READ_SPECIAL.SGL. This is the file that FAS looks for when the ‘Read Special’ button is clicked. See also section 2.2.7 ]

      6. Getting shot and signal lists

        7. The shot and signal lists can be retrieved by clicking on the ‘Get Shot List’ or the ‘Get Signal List’ buttons. If clicked, a window similar to the Save window comes up and the file can be selected by clicking on its name. When ‘Read’ is clicked the shots or signals are put into the appropriate widget list.

      7. The Read Special button

        8. The Read Special button is extremely useful. When this button is clicked it gets the list of signals in the file READ_SPECIAL.SGL, then gets the most recent shot number, and then reads in the data for the signals.

        [Note: Before the Read Special button can be used a list of signals must be saved in the file READ_SPECIAL.SGL, this file must be located in the same directory in which FAS was started. See also section 2.2.5 ]

         

         

         

      8. Experiment (CURRENTLY DISABLED)

      The ‘Read Special’ button (section 2.2.7) and the ‘Get Most Recent Shot Number’ (see section 2.2.1) button get the most recent shot number. Setting the experiment option specifies whether the shot number obtained is to be for another MDSplus server.

    3. Deleting channels from memory

      4. Channels in memory can be removed using the delete feature.

      The delete process must first be activated. This is done by clicking on the ‘Delete’ button. When clicked upon it changes to ask for a confirmation of ‘Yes’ or ‘No’. If the channels in the list are clicked upon, their corresponding numbers appear in the ‘Channels’ box. Channels number can also be typed into the box separated by commas. A range of channels can be specified by typing in the two extremes separated by a colon. To delete all the channels simply type in ‘all’.

      e.g. To delete channels 1, 2, 6 to 11 and 20, type in 1,2,6:11,20

      [Note: The message box at the bottom will display the channel numbers that are to be deleted. ]

    4. Plotting data

      5. From the main menu click on Window to bring up the Window menu which should look like:

      There are two lists towards the bottom of the screen called ‘Channels Currently in Memory:’ and ‘Channels To Plot In Window-<window number>’, referred to as List-1 and List-2.

      List-1 displays the channels that have been read in, it can be manipulated using the Display Channels box and the Match Channels box. The channels are all numbered, therefore simply type in the names of the channels in the Display Channels box and click on display. Match Channels is used to pick out channels with similar characters in their name.

      e.g.-1: To display channels from 1 to 5, 8, 10 and 13 to 20 type 1:5,8,10,13:20 in the box and click on display.

      e.g.-2: To display channels with the word PLASMA anywhere in the name type PLASMA in the Channels To Match box and click on Match Channels.

      List-2 displays all the channels that have been selected to be plotted, channels can either be selected simply by clicking on them in List-1 or by manipulating the display and then clicking on Select All. Channels can be deselected by clicking on them in List-2 or by clicking on Clear Window.

      The above process of selecting channels to plot can be done several times to create up to 10 different windows.

      Using the above Window option, the number of the windows can be set. The channels in List-2 will then be assigned to this window.

      Other options on this window are:

      1. Plot style

        2. This option controls the manner in which the traces are plotted in the window. Every window can have its own individual plot style.

        1. Panel

          2. This is the default. In this mode the traces will be plotted one below the other, each in its own panel.

        2. Overlay

          3. In this mode all the channels in the window are plotted in the same panel, one on top of the other.

        3. Custom

        When Custom is clicked a box appears in right hand corner which looks like:

        This allows you to create each panel individually. To create a panel, select signals in the usual way, then, on the next panel, select another set of signals, etc. The panels will be plotted one below the other but the signals within each panel will be overlaid.

      2. Panel margins

        3. This option allows the user to change the spacing between the panels.

        1. None

          2. This is the default. There will be no gap between panels.

        2. Auto

          3. In this the mode the panel margins are set automatically depending upon the number of panels in the window.

        3. Manual

        When clicked the panel margins can be specified manually in the Plot Options window, see section 2.6.2

      3. Xrange

        4. This option lets the user specify over what time ranges he/she wants the graphs to be plotted.

        1. Universal

          2. This is the default. In the universal mode all the graphs have the same time range.

        2. Sequential

          3. In the sequential mode the time range is plotted sequentially for subsequent panels, this mode is useful when one graph is to be plotted in detail over a large time range. To do this select the same signal many times and specify the start and the increment in the sequential box that looks like:

          If you have chosen the signal n times the graph will be plotted from the start to n times the increment.

        3. Manual

        Click on manual to be able to set the range manually. This can be done in the Plot Options window, see section 2.6.2

      4. Yrange

        1. Individual

          2. This is the default for panel mode (section 2.4.1.1). In the individual mode, the y-range is set automatically and is different for each trace depending on the graph. The range is calculated automatically to include the whole trace.

        2. Universal

          3. This is the default for overlay and custom modes (sections 2.4.1.2 & 2.4.1.3). In the universal mode the y-range is constant for all the graphs.

        3. Manual

      Click on manual to be able to set the range manually. This can be done in the Plot Options window, see section 2.6.2

      After selecting the required signals click on Return to return to the main menu where the graph will be drawn. The different windows created can be viewed by clicking on the window button and selecting the appropriate value.

    5. Zooming

      6. Click on the Zoom button to bring up the zoom panel which looks like:

      At present only the X - Zoom. Click on X - Zoom to bring up the X - Zoom panel which looks like:

      To zoom over part of the graph, click in two areas of the graph (a line connects the first point to the mouse location). The graph will be replotted with the time range the line covered. When you are done with the zoom click on the ‘Return’ button. This will then ask for a confirmation for saving the current X-Range. If the ‘Don’t Save’ option is chosen the X - Range as selected when entering X - Zoom is restored.

    6. Customizing plots

      7. When you click on Plot the Plot menu appears which looks like:

      1. Changing Settings

        2. The panel below appears, when selecting any option from the plot menu. This determines exactly which traces are changed.

        1. Individual, Panel and Window Settings

        Changes in customizing plots are made on an Individual, Panel or Window basis. (see section 1.4 for terminology).

        Selecting Window causes all changes to be adopted by all Traces within the given Window.

        Selecting Panel causes all changes to be adopted by all Traces within the given Panel (in the given Window).

        Selecting Individual causes all changes to be adopted by the trace represented by the given Element (in the given Window). See section 1.4 for an explanation of Element.

        [Note: Panel mode can only be selected if custom has been chosen from the ‘Window’ window (see section 2.4.1).]

      2. X and Y axis

        3. If the X-Axis or the Y-Axis buttons are clicked their respective windows appear (as shown below).

        For the range you again get a choice of universal, individual or specify. In the individual and window modes clicking universal will set the range to cover all traces. In the panel mode universal will set the range to cover all traces within the same panel.

        [Note: In the Y - Axis window the titles ‘Left Margin’ and ‘Right Margin’ stand for bottom and top margins respectively. Margins are a percentage of the window, i.e. A margin of 5 is not 5 pixels but 5% of the window.]

         

      3. X and Y ticks

        4. A similar window is opened when X-Ticks or Y-Ticks is clicked upon which looks like:

        This panel can be used to customize the ticks on the x- and y-axes.

      4. Color

        5. Click on Color to bring up the Color panel which looks like:

        This window allows the user to manually specify the color of a trace. This is useful when doing overlay plots. The color table can be chosen by clicking on the table. To select the color drag the index along the color table, the color in the box on the right will change according to where the index is positioned.

        [Note: Only one color table can be used for each window. So if you change the color table whilst making changes other trace colors may be affected.]

      5. Style

        6. Click on Style to bring up the Style panel which looks like:

        In this panel the user can specify how points are joined to together, e.g. solid lines, dashes, etc. The thickness of the trace can also be specified.

      6. Smoothing

        7. Click on Smoothing to bring up the Smoothing panel which looks like:

        This option provides the smoothing function available in IDL.

        The ‘Number of Adjacent points to Average over’ option is identical to the IDL keyword NSUM in the call to PLOT. Only one point is plotted over each averaged period.

        [Note: Selecting any smoothing option (in this window) does not modify the data.]

      7. Symbol

      Click on Symbol to bring up the Symbol panel which looks like:

      This window can be used to replace the points in traces with another symbol, such as crosses, triangles, etc.

      The plotting symbols can be used to differentiate between traces if they are overlaid. When none is selected the plotting symbol is a point, if a cross is used the graph will be crosses connected by lines. The trace functions allows you to decide whether you want the points to be connected by lines or not.

    7. Creating a page

      8. When you click on the Page button the page maker appears (shown on next page).

      Initially, cell 1 is active and occupies the whole page, window 1 is assigned to it. Cells can be added or deleted using the ‘Add Cell’ and ‘Delete Active Cell’ buttons. To select a cell simply click on its corresponding radio button. Windows can be assigned to cells by using the

      buttons. A selected cell will have a small box at its center and eight similar boxes on its border the box in the middle is used to move the cell. Simply click on the central box once and then the cell will follow the mouse. The boxes on the corners are used to change the shape and size of the cell, click once on the box and move the mouse. The boxes midway between the corners are also used for a similar purpose but the code for them has not been written as yet, they therefore at present do nothing. Every time a new cell is added, it is automatically selected and is as big as the page.

      Therefore to create a page, shape and position the first cell and assign a window to it, then add a new cell and so on. After a page has been completed select a new page number which can be done using the < and > buttons in the top left corner of the window. The whole process can be repeated to make a new page.

    8. Printing

      9. From the main window click on the print button to bring up the print panel:

      You may choose to print windows, or pages you have specified. Any of 10 pages or windows can be printed at any one time by clicking the numbered buttons. The Output options lets the user send the output to either a printer or file, or both. (The postscript file is written to the directory assigned by the logical GRF, if defined, or to your login directory.) The button next to the ‘Printer Queue:’ is a pulldown menu which lists all the printers, click on a printer to select it. Using the ‘type’ option the user can choose between color or B/W output. Processing

      Many of the processing routines can be accessed via the graphical interface. For specific information on processing routines see section 3.4.2

    9. Processing Window

      10. When you click on the Process button, the process window is brought up which looks like:

       

      1. Channels in memory

        2. This list displays all the channels in memory.

      2. Channels to process

        3. This list displays all the channels that have been selected for processing. To add a channel to this list simply click on it in the ‘Channels in memory’ list.

        To remove a channel from this list just click on it.

      3. Display Channels

        4. This box can be used to manipulate the ‘Channels in memory’ list. Type in the numbers of the channels to be displayed and press Return (or Enter) on your keyboard, to display these channels.

        e.g. To display channels 1,2,5,10 to 20 type in 1,2,5,10:20

      4. Filter

        5. The filter provides another way of manipulating the ‘Channels in memory’ list. Type in the filter with ‘*’ as the wildcard to search for the filter.

        e.g. For all channels with ‘rf’ anywhere in the name the filter will be ‘*rf*’.

      5. Select All

        6. Click on this button to select all Channels (currently in the ‘Channels in memory’ list) to be processed.

      6. Clear list

      Click on this button to clear ’Channels to process’.

      Towards the top of the screen you will notice a set of buttons with the names of processes beside them, clicking on these buttons will bring up other windows that are specific to that routine.

      [Note: If no channels are selected the buttons are insensitive. Basically nothing can be done unless some channels are selected.]

    10. Integrate

      11. Clicking on this button will bring up the integrate window which looks like:

      1. Selecting the time range

      The time range over which to integrate can be set by clicking on ‘Specify time range’. The start and finish times are then displayed. This time range is common to all the channels, if there is no common time range both are set to zero and the channels are integrated over their own respective time ranges. You can input a new start and finish time if you wish to do so. The time range for each channel can also be set individually, this is done by clicking on the ‘Individual time range’ button. The start and finish times shown are those of individual channels, these values can also be changed. You can scroll through the values for all the channels by using the < > buttons. You can also view a channels time range by typing in its number in the ‘Number:’ box.

      There are two buttons at the bottom of the integrate window, one is ‘Replace channels in "Channels to process list"’ and the other is ‘Delete old channels after operation’. The first button will cause the list of selected channels to be replaced by the new channels caused by the integration. If the second button is clicked then the present selected channels will be deleted from memory after the integration has been completed.

    11. Polynomial

      12. Clicking on this button brings up the polynomial window.

      This window allows channels to be combined as polynomials to create new channels.

      1. Data I/O

        2. For the ‘Number of output channels’ select 1 if you want the channels to be added together, or select ‘=Number of input channels ‘ if you want the same operation to be carried out on all the selected channels.

        Channels that do not have identical time ranges cannot be added together, interpolate if set makes sure they do.

        ‘Update process list’ and ‘Delete old channels’ are used to manipulate the selected channels list.

      2. Inputs

        3. If you select global then all the channels will be given the same value. Select individual to specify values for channels individually. Use the < and > buttons to scroll through the channels.

        An offset can also be subtracted by specifying a number in the offset box. If subtract average is clicked the offset box will change to display the ‘Time Range’. Here you can specify the time range over which the average must be calculated. The format is <start time>,<finish time>.

      3. Easy Options

      If average is selected most of the functions in the window will be disabled and the formula will change to show you what the result will be. The result is the average of all the channels. To normalize the result click on normalize, you can either normalize from -1 to 1 which is the default or specify the normalizing factor.

      [Note: In all the boxes whenever a value is typed in always press Return (or Enter) on your keyboard after doing so.]

    12. Spectral

      13.  

      Clicking on this button brings up the spectral window.

      This window allows either the FFT, Bi-coherence, Cross spectrum or zero cross spectrum to be calculated for the one or more channels contained in the ‘channels to process’ list.

      1. Setting the time range

        2. The time range can either be set to ‘Universal’ or ‘Individual’ for all the channels to be processed. If ‘Individual’ is selected, the time range can be altered by typing in the desired range in the ‘Start time:’ and ‘Finish time:’ fields.

      2. ‘Output’ Options

        3. The spectral operation (FFT, Bi-coherence and Cross spectrum only) can be used to create either one new channel (Amplitude or Phase) or two new channels (Amplitude and Phase) for each channel selected for processing. The Phase can be output in either ‘Radians’ or ‘Degrees’.

      3. ‘Window’ options

        4. The window options for the spectral operation (FFT, Bi-coherence and Cross spectrum only) are Square, Hanning, Hamming and Blackman. The Hanning window is the same as the Hamming window with alpha set to 0.54. The Alpha value must lie between 0.5 and 1.0 and is only active when the Hanning window is selected.

      4. ‘Reference channel:’

        5. This option is activated when the Bi-coherence or Cross spectrum operation is selected. It is the channel used as a reference from which to calculate the Bi-coherence or Cross Spectrum. The default is the first channel in the ‘Channels to process:’ list.

      5. Zero cross function

Selecting this function activates the zero cross window. Options include, subtracting offsets, smoothing the channel, interpolating the channel to create a time range matching the original channel and a half cycle option used to calculate the frequency based on every zero cross (if not set then every alternate zero cross is used).

  • FAS Macros

    1. Introduction

      2. Users are now able to write macros in FAS. Macros are an essential and powerful option. They allow the user an increased degree of flexibility and make the code more powerful. This chapter is intended to give the user a better understanding of the internal workings of FAS, such as the way data is stored and handled. A complete specification of all user routines and example macros have been provided to help the user learn how to write FAS routines.

    2. Macro Environment

      1. Basics

        2. FAS macros are written in IDL. As a result the macro is a program that is run when called. Apart from all the usual IDL commands, users also have access to certain FAS library routines that interact with the widget interface and the data stored in FAS.

        For example if users wish to perform a calculation on a set of channels in memory not already provided by FAS they could write a macro that will do it for them. They would first have to extract the data from memory; this can be done by using one of the library routines. They could then perform calculations and put the channels back into memory using another FAS library routine.

      2. Macro window in FAS

        3. Macro’s can be run by selecting the appropriate file from the macro window. The macro window within FAS is shown below.

        Simply click on the appropriate file to select the macro. Input parameters can also be specified in the macro box. When all options have been specified click on Run to execute the macro.

        NOTE: If you are changing a previously run macro you must select the ‘Exit to IDL’ option and then use ‘.run <macro_name>‘ in order to recompile the procedure. (See section 3.2.5)

      3. Using Macros from the IDL command line

        4. FAS macros can also be used from the IDL command line.

        These macros must contain the FAS_SETUP procedure , which checks to see if the FAS environment is set correctly. If it is not set correctly then it automatically sets up the FAS structures and handles and routines.

        Macros are called like any other procedure from the IDL prompt, and the full functionality of the interactive IDL mode can be used.

        Typing FAS at the IDL (or FAS) prompt will initiate the FAS window environment.

         

      4. Switching between the FAS window and command line modes

        5. Users can switch between the two different modes by selecting the ‘Exit to IDL’ option from the ‘File’ menu to exit the FAS window environment , and typing FAS at the IDL prompt to enter the FAS window environment. Selecting the ‘Quit to IDL’ option from the ‘File’ menu kills the FAS environment, with the loss of all previously held information (including data).

         

      5. Debugging and recompiling macros

      If users are debugging macros while in the FAS window environment, they must recompile the macro after a change is made (since IDL does not automatically recompile changed procedures). On Unix, you may simple type .RUN <macro_name> at the IDL prompt while the widget interface is running. At present the only way to do this on VMS is to select the ‘Exit to IDL’ option from the ‘File’ menu and type at the IDL (FAS) prompt :-

      FAS> .RUN <MACRO_NAME>

      Then to re-enter the FAS window environment type:-

      FAS> FAS Internals

    3. FAS Internals

      4. FAS uses IDL ’structures’ and ‘handles’ to store data. Handles are similar to pointers in C or Pascal. Handles use memory efficiently which gives FAS the ability to store large sets of data. An additional advantage is that if the ID of a handle is known (stored as a long integer) then the data it points to can be accessed globally. IDL ‘system variables’ are used to store these long integers. These are global variables (starting with an exclamation mark ! followed by one or more characters) in which the ID of the handle(s) is stored. Thus data can be accessed from anywhere within IDL.

      When a channel is read in, all the information that is used to represent a channel (e.g. data, time information, units, etc.) is stored in a structure. This structure is then assigned to a handle. Therefore, if the data of a particular channel is required, its corresponding handle must first be obtained. Once that is done, the actual set of data is obtained. Storing data is basically the process in reverse. The user is not expected to use handles and system variables directly; a set of user routines is available to do all this. For reference, the data structure is represented in a diagram on the previous page.

    4. Organization of routines

      5. All the user routines in FAS can be classified into the following types:

      1. General FAS routines

        2. These routines are specific to FAS, but general in their use. The more commonly used routines have shorter names, helping to cut down on the size of the text for the macro.

        LASTCHAN

        Gets the channel number of the last channel in memory.

        LASTSHOT

        Gets the shot number of the most recent shot.

        FAS_SETUP

        Used to setup the IDL environment for FAS.

        FAS_LIST

        Gets a list of either shots or item names from a file

      2. Calculation

        3. These routines are used to process channels. The list of processing routines in FAS is not exhaustive. The ones that have been written perform calculations that are used often by many users, and many more are planned.

        The macro feature will enable users to write their own processing routines if they need to do a calculation not provided for by a FAS routine. The following routines come under this category:

        FAS_0CRS

        Calculates the zero cross frequency of the channel.

        FAS_CRSP

        Calculates the cross spectrum and the bi-coherence between two channels.

        FAS_FFT

        Calculates the FFT of a channel.

        FAS_INTG

        Calculates the integral of a channel.

        FAS_INTERPOL

        Interpolates a channel, can be used to increase the number of data points or create a new time base.

        FAS_POLYNOMIAL

        Combines channels in polynomial combinations.

      3. Data Access

        4. The routines in this category are used to handle data I/O. Using these routines the user can read in data from the IDA files, create or modify channels and write channels to IDA files.

        FAS_READ

        Reads in channels from the IDA files.

        FAS_WRITE

        Writes out channels to a specified file.

        FAS_READ_FILE

        Reads in data from a specific file.

        FAS_MODIFY_CHAN

        Changes the data structure of a channel. Can be used to create a new channel.

        FAS_DELC

        Deletes a specified list of channels from memory

        FAS_DATA

        Gets data from the data structure within FAS.

        FAS_NAME

        Gets the signal name of the channel from the data structure within FAS.

        FAS_SHOT

        Gets the shot of the channel from the data structure within FAS.

        FAS_NPTS

        Gets the number of data points from the data structure within FAS.

        FAS_STRUCT

        Gets the complete data structure within FAS

        FAS_TIME

        Gets the time vector from the data structure within FAS.

      4. Plotting

        5. These routines allow the user to plot channels and modify traces. They provide a programmable interface similar to the widget interface.

        FAS_PLOT_OPTIONS

        Allows the user to set up the plot options. Does everything that can be done from the ‘Plot Options" window.

        FAS_WINDOW

        Allows the user to plot windows. Does everything that can be done from the ‘Window’ window.

      5. Printing

        6.  

        FAS_PRINT

        Allows the user to produce PostScript files and print them. (Only of FAS ‘Window’ plots at present).

      6. Rules

    There are certain rules that need to be followed when writing a macro, they are:

      • All macros must be procedures. I.e., they must not return values.

      • All macros should contain ‘FAS_SETUP’ as the first line (unnecessary processing is skipped).

      • The name of the macro text file must be the same as the name of the macro and should have ‘.pro as the extension.

      • It is advisable not to use the system variables and data structures within FAS directly. If used improperly, FAS could crash and all data may be lost.

        1. Hints

    Useful information for writing FAS macros.

      • You may abbreviate keywords. Set keywords to true with ‘/’ (i.e. /<KEYWORD> is identical to <KEYWORD>=1).

      • Make arrays with [ ] (e.g., to change the scalar variable SHOT to an array add square brackets, SHOT = [SHOT]

      • Make use of the VERBOSE keyword (/V) when debugging macro code, it will inform you of any errors encountered.

      1. Examples

        2. Here are a few examples of source code that might constitute a macro:

        1. Plotting Channels

          2. An example macro is given below (; is the comment symbol in IDL).

          PRO AUTO_PLOT, SHOT = SHOT, PRINT = PRINT, COLOR = COLOR, $

          OVERLAY = OVERLAY, NAMEFILE=NAMEFILE, VERBOSE = VERBOSE

          ;------------------------------------------------------------------------------------------------------

          ;

          ; This macro produces panel plots (or overlay plots) of the same signals for ; different shots, with the option to print the plots in B/W or color (to

          ; postscript file only)

          ;

          ;

          ; KEYWORDS:

          ;

          ; SHOT:

          ;

          ; This keyword is set to the first SHOT of the 10 consecutive shots

          ; to be used. If not supplied the most recent shot is used.

          ;

          ; PRINT:

          ;

          ; Set this keyword to a non-zero value to create a PostScript file of ; all the ‘Windows’. The file is called FAS_MACRO.PS and is ; contained in the directory defined by the logical SYS$SCRATCH.

          ;

          ; COLOR:

          ;

          ; Set this keyword to a non-zero value to make the postscript file ; color instead of black and white. (Only applicable if PRINT is set).

          ;

          ; OVERLAY:

          ;

          ; Set this keyword to a non-zero value to produce ‘Overlay’ plots ; instead of ‘Panel’ plots.

          ;

          ; NAMEFILE:

          ;

          ; Set this keyword to the name of a file which contains a list of

          ; item names. If missing a default is used.

          ;

          ; VERBOSE:

          ;

          ; If this keyword is set, error messages from the FAS routines will

          ; be printed to the screen.

          ;

          ;------------------------------------------------------------------------------------------------------

           

          ;

          ; Call FAS_SETUP to initiate handles and system variables

          ;

          FAS_SETUP

          ;

          ; Check to see if a file with a list of names has been provided. If not supply

          ; default

          ;

          IF NOT KEYWORD_SET(NAMEFILE) THEN NAMEFILE=‘USER:[POCOCK]BTD.SGL’

          ;

          ; Call FAS_LIST to obtain a list of signals from a file saved using the ‘Save ; Signal List’ option in FAS.

          ;

          FAS_LIST, FILE=NAMEFILE, SIGNAL_LIST = NAMES_LIST

          ;

          ; As there is a limit of 10 FAS ‘Windows’ then ensure that there is a ; maximum number of 10 signal names. If there are more than 10 signal ; names just use the first 10 in the list. Also check there is at least one name.

          ; Note: $ is the line continuation mark and & marks a new line of code.

          IF N_ELEMENTS(NAMES_LIST) EQ 0 THEN BEGIN

          PRINT,’No Items were found’ & RETURN & ENDIF

          IF N_ELEMENTS(NAMES_LIST) GT 10 THEN NAMES = NAMES_LIST(0:9) ELSE $

          NAMES = NAMES_LIST

          ;

          ; Obtain 10 consecutive shots starting with the value supplied by the keyword ; SHOT. If not set, get most recent shot. Note the use of the INDGEN

          ; function, which returns [0,1,2,3,4,5,6,7,8,9]. For more on array generation ; in IDL see the online help under "Array creation routines"

          ;

          IF NOT KEYWORD_SET(SHOT) THEN SHOTS_LIST = LASTSHOT() - INDGEN(10) $

          ELSE SHOTS_LIST = INDGEN(10)+FIX(SHOT)

          ;

          ; Now read the data into memory.

          ;

          FAS_READ, SHOTS = SHOTS_LIST, NAMES = NAMES, /BY_ITEM

          ;

          ; Check to see how many channels are present

          ;

          VALID = LASTCHAN()

          ;

          ; If there are no valid channels then just return

          ;

          IF VALID EQ 0 THEN RETURN

          ;

          ; Obtain all of the signal names

          ;

           

          ALL_NAMES = FAS_NAME(/ALL)

          ;

          ; Now depending on how many channels are valid set out the plot style in ; different formats. Need to loop for each signal. Also set plot style.

          ;

          WINDOW = 0

          IF KEYWORD_SET(OVERLAY) THEN PLOT_STYLE = 2 ELSE PLOT_STYLE = 1

          FOR LOOP = 0, N_ELEMENTS(NAMES)-1 DO BEGIN

          ;

          ; Find all channels with the correct signal name using the IDL

          ; "WHERE" function.

          ;

          MATCH = WHERE(ALL_NAMES EQ NAMES(LOOP),COUNT)

          IF COUNT NE 0 THEN BEGIN

          ;

          ; Found one or more matches so make channel list.

          ; (Channels start at 1, Indices start at 0)

          ;

          CHANS = MATCH + 1

          WINDOW = WINDOW + 1

          ;

          ; CHANS now contains the channel numbers to be plotted ; in window.

          ;

          ; Call FAS_WINDOW to create the plot.

          ;

          FAS_WINDOW, WINDOW = WINDOW, CHANS = CHANS, $ PLOT_STYLE = PLOT_STYLE, XMODE = 1, YMODE = 2, /VERBOSE

          ENDIF

          ENDFOR

          ;

          ; Check for print option and make sure there is something to print

          ;

          IF KEYWORD_SET(PRINT) AND WINDOW NE 0 THEN BEGIN

          ;

          ; Assign WINDOW_PRINT all of the ‘Windows’ to be printed.

          ;

          WINDOW_PRINT = INDGEN(WINDOW)+1

          ;

          ; Call FAS_PRINT to create the PostScript file

          ;

          FAS_PRINT, WINDOW = WINDOW_PRINT, COLOR = COLOR

          ENDIF

          END

           

        2. Changing the plot options

         

        This program demonstrates how to change the plot options of traces. Channel numbers are not required to change the plotting options. However knowing the number of plots in a window and the mode does help. Let us assume that window 1 has 4 panels in custom mode with 2 traces per panel. This example will demonstrate how to change the colors of the traces and change the xrange.

        PRO CHANGE__PLOT_OPTIONS

        ;

        FAS_SETUP

        ;

        ; Change the xrange on all traces in the window

        ;

        FAS_PLOT_OPTIONS, WINDOW=1, XRANGE =[0,1]

        ;

        ; Change the colors of the traces in panel 1 individually and change

        ; the color of the traces in panel 2 to the same color.

        ;

        FAS_PLOT_OPTIONS,WINDOW=1,ELEMENT=1,$

        COLOR=100, LOADCT=5

        FAS_PLOT_OPTIONS,WINDOW=1,ELEMENT=2,COLOR=200

        FAS_PLOT_OPTIONS,WINDOW=1,PANEL=2,COLOR=150

        END

      2. Commonly used FAS functions.

        1. FAS_DATA

          2. PURPOSE:

          This function returns the data of the channel(s) specified by I, as a 1-D (or 2-D if an array of channels is specified) floating point array. If no valid channels are specified this function returns -1.

          CALLING SEQUENCE: RESULT = FAS_DATA(I)

          ARGUMENTS:

          *I (if ALL is not set):

          An integer array containing the channel numbers from which to extract data.

          KEYWORDS:

          ALL:

          Set this keyword to a non-zero value to extract data from every channel.

          VERBOSE:

          Set this keyword to a non-zero value to display informative messages to the IDL command line.

          NOTE: If more than one channel is specified and the array of each channel is not of the same size and type, this function will return 0

        2. LASTCHAN

          3. PURPOSE:

          This function returns the channel number of the last channel in memory. This helps the user keep track of the channels in memory. If no channels are present then 0 is returned.

          CALLING SEQUENCE: RESULT = LASTCHAN()

           

        3. LASTSHOT

          4. PURPOSE:

          This function returns the most recent COMPASS or START shot.

          CALLING SEQUENCE: RESULT = LASTSHOT()

          KEYWORDS:

          START:

          If this keyword is set the program will return the most recent START shot as opposed to the most recent COMPASS shot (this is the default).

           

          NOTE: If running a macro that waits until a new shot is received, the necessary IDA files may still be open and being written to. Users are advised to perform these checks themselves from within the macro, to avoid errors.

        4. FAS_NAME

          5. PURPOSE:

          This function returns a string scalar/array containing the name of the signal of the channel(s) specified by I, if no valid channels are specified then this function returns ‘-1’.

          CALLING SEQUENCE: RESULT = FAS_NAME(I)

          ARGUMENTS:

          *I (required if ALL not set):

          An integer array containing the channel number(s) from which to extract the signal name(s).

          KEYWORDS:

          ALL:

          Set this keyword to obtain the signal names of all the channels in memory.

          VERBOSE:

          Set this keyword to a non-zero value to have informative messages displayed to the IDL command line.

        5. FAS_NPTS

          6. PURPOSE:

          This function returns the number of data points for the channel(s) specified by I, as a long integer/array. If no valid channels are specified this function returns -1.

          CALLING SEQUENCE: RESULT = FAS_NPTS(I)

          ARGUMENTS:

          *I (required if all not set):

          An integer array containing the channel number(s) from which to extract the number of data points.

          KEYWORDS:

          ALL:

          Set this keyword to obtain the number of data points from every channel in memory.

          VERBOSE:

          Set this keyword to a non-zero value to display informative messages to the IDL command line.

        6. FAS_SHOT

          7. PURPOSE:

          This function returns the shot(s) of the channel(s) specified by I, as a long integer/array. If no valid channels are specified this function returns -1.

          CALLING SEQUENCE: RESULT = FAS_SHOT(I)

          ARGUMENTS:

          *I (required if ALL not set):

          An integer array containing the channel number(s) from which to extract the shot(s).

          KEYWORDS:

          ALL:

          Set this keyword to a non-zero value to extract the shots from all the channels in memory.

          VERBOSE:

          Set this keyword to a non-zero value to display informative messages to the IDL command line.

           

        7. FAS_STRUCT

          8. PURPOSE:

          This function returns the complete data structure associated with the channel specified by I. If the channel number specified is invalid then this function returns -1.

          CALLING SEQUENCE: RESULT = FAS_STRUCT(I)

          ARGUMENTS:

          *I:

          An integer containing the channel number from which to extract the data structure.

          KEYWORDS:

          VERBOSE:

          Set this keyword to a non-zero value to display informative messages to the IDL command line.

        8. FAS_TIME

        PURPOSE:

        This function returns the timebase of the channel(s) specified by I, providing that the timebases are compatible (i.e. the number of data points is the same for all channels specified). If no valid channels are specified this function returns -1, if incompatible time bases are specified then this function returns 0.

        CALLING SEQUENCE: RESULT = TIME(I)

        ARGUMENTS:

        *I (required if ALL not set):

        Set this keyword to an integer array containing the channel number(s) from which to extract the time base(s).

        ALL:

        Set this keyword to a non-zero value to extract the time base(s) of all the channels.

        VERBOSE:

        Set this keyword to a non-zero value to display informative messages to the IDL command line.

      3. Reference for user routines

        1. General Points

          2. All procedures written in FAS (which are currently supported) use KEYWORDS to set flags/options, and not ARGUMENTS.

          KEYWORDS are optional. Keywords that are always required for sensible execution are denoted by an asterisk. For more on how to use KEYWORDS see the IDL online help or Chapter 1 of the "IDL User’s Guide"

          In general CHANS needs to be specified. However in processing routines if it is omitted then the channels in the ‘processing list’ in the FAS window environment are used instead.

        2. FAS_0CRS

          3. PURPOSE: To calculate the zero cross frequency of a channel.

          CALLING SEQUENCE: FAS_0CRS

          KEYWORDS:

          *CHANS:

          A one dimensional integer array containing the channel numbers of the channels whose zero cross frequency is to be computed. If not set the list of channels will be extracted from memory. If an invalid channel is specified, it will be ignored.

          EXE_MESS:

          It returns any messages from the program as it is executed.

          EXE_CODE:

          It contains values depending on the execution of the program. A negative value is returned if the operation is unsuccessful.

          1: Some channels do not have enough zero crosses for operation

          0: Operation successful

          -1: No channels in memory

          -2: OFFSET is not of the correct type

          -3: INTERPOLATE is not of integer type

          -4: HALF_CYCLE is not of integer type

          -5: SMOOTH is not of integer type

          -6: SUB_AVE must be of integer type

          -7: SA_TR is not of the right type

          -8: SA_TR has an odd number of elements

          -9: TIME_RANGE is not of the correct type

          -10: TIME_RANGE has an odd number of elements

          -11: All channel numbers are invalid

          VERBOSE:

          If this keyword is set, the program will print out messages to the screen.

          INVALID:

          Receives the channel numbers of any invalid channel numbers that have been specified.

          BAD_DATA:

          Set this keyword to receive the channel numbers of channels that did not posses sufficient zero crosses to enable calculation of the frequency..

          TIME_RANGE:

          A two dimensional array that holds the time ranges over which the 0CRS is to be performed. The first column of the array must hold the start times and the second the finish times. Alternatively, the array can be one-dimensional with the start and finish times alternating. If all the time ranges are not specified then the last time range is replicated for the remaining channels. FAS_0CRS will not accept an odd number of elements.

           

          OFFSET:

          A one dimensional float array that specifies the offsets to be removed from the channels before the zero cross frequency is calculated.

          SMOOTH:

          A one dimensional integer array that specifies which channels are to be smoothed. If an element is 0 then the corresponding channel will not be smoothed. The smoothing value must be an odd integer greater than 2. This value specifies the number of points over which the smoothing is to be done. If an even number (n) is specified then n+1 is used.

          SUB_AVE:

          A one dimensional array with 1s and 0s. A 1 signifies that the offset removed must be the average of the channel and a 0 signifies that the offset removed must the offset specified by the OFFSET keyword.

          SA_TR:

          This keyword is identical to the TIME_RANGE keyword above. SA_TR however affects only the offset. If SUB_AVE is set then the time range over which the average is to be calculated can be set using this keyword.

          INTERPOLATE:

          A one dimensional array with 1s and 0s. A 1 signifies that the resultant data will be interpolated to create a uniform time range matching the original time range. If not set (i.e. 0) then an irregular time range is created.

          HALF_CYCLE:

          A one dimensional array with 1s and 0s. If set (i.e. a 1) the frequency is calculated by taking into account every zero cross. If not set (i.e. a 0) then every alternate zero cross is used.

           

        3. FAS_CRSP

          4. PURPOSE:

          To calculate the cross spectrum between two channels over a specified time range. FAS_CRSP returns either the amplitude, the phase or both. It also allows windowing operations.

          CALLING SEQUENCE: FAS_CRSP

          KEYWORDS:

          REF_CHAN:

          The cross spectra of the list of channels specified by CHANS will be performed with REF_CHAN. This being an integer. If REF_CHAN is invalid, execution will stop.

          *CHANS:

          A one dimensional integer array containing the channel numbers to be Fourier Transformed. If CHANS is not set, the channel numbers will be extracted from the list of selected channels in memory. If an invalid channel number is specified, FAS_CRSP will ignore it and carry on.

          BI:

          Set this keyword to calculate the bi-coherence of the channel instead of the cross spectrum.

          EXE_MESS:

          Returns any messages from the program as it is executed.

          EXE_CODE:

          Returns values based on the execution of the program. If an error has occurred a negative value is returned.

          0: Operation successful.

          -1: REF_CHAN is not set.

          -2: REF_CHAN is not an integer.

          -3: REF_CHAN is not valid

          -4: ALPHA must be a floating point value.

          -6: CHANS must be an integer.

          -7: No channels in memory.

          -8: TIME_RANGE is not of the correct type.

          -9: TIME_RANGE does not have the correct dimensions.

          -10: All channel numbers are invalid.

          VERBOSE:

          If this keyword is set, the program will display messages to the screen.

          INVALID:

          Returns the channel numbers of any invalid channels that have been specified.

          BAD_TIME:

          It returns the channel numbers of any channels whose time bases do not match the time base within the given time range. FAS_CRSP will skip over these channels.

          TIME_RANGE:

          A two dimensional array that holds the time ranges over which the CRSP is to be performed. The first column of the array must hold the start times and the second the finish times. Alternatively, the array can be one-dimensional with the start and finish times alternating. If all the time ranges are not specified then the last time range is replicated for the remaining channels. FAS_CRSP will not accept an odd number of elements.

           

          AMPLITUDE:

          Set this keyword to calculate the amplitude of the cross power spectrum.

          PHASE:

          Set this keyword to calculate the phase of the cross power spectrum. BI has no effect on the phase.

          NOTE: If neither amplitude or phase is set then both are calculated. This is the default. If amplitude is set and not phase then only amplitude is calculated; similarly for phase.

          DEGREE:

          If set it will cause the phase to be output in degrees rather than in radians.

          HANNING:

          Set this keyword to use the Hanning window on the CRSP.

          ALPHA:

          Set this value between 0.5 and 1.0 to manipulate the Hanning function. This keyword has no effect if HANNING is not set. The default value is 0.5.

          HAMMING:

          Use the Hamming window on the CRSP. In fact the Hanning window with alpha set to 0.54 will produce exactly the same result.

          BLACKMAN:

          Use the Blackman window.

           

        4. FAS_DELC

          5. PURPOSE: This routine can be used to delete channels from memory.

          CALLING SEQUENCE: FAS_DELC

          KEYWORDS:

          ALL:

          Set this keyword to delete all channels from memory. [Has preference over CHANS keyword].

          *CHANS (required if ALL is not set):

          Set this keyword to an array containing the numbers of the channels to delete. The numbers must be integers or an error will occur.

          KEYWORDS:

          EXE_CODE:

          Set this keyword to return the execute code of the program.

          1: Operation successful

          -1: No channels in memory

          -2: Required parameters not given

          -3: CHANS must be an integer

          -4: All channel numbers are invalid

          -5: Required parameters not set

          EXE_MESS:

          Set this keyword to return the execute messages of the procedure. This is useful when VERBOSE is not set.

          VERBOSE:

          Set this keyword to display all the procedures messages to the screen.

          INVALID:

          Set this keyword to return all the invalid channel numbers.

          EXAMPLES:

          To delete channels 2,3 and 10 and to view any messages:

          FAS_DELC, CHANS=[2,3,10], /VERBOSE

          To delete all the channels in memory and return the EXE_CODE to CODE and EXE_MESS to TELL:

          FAS_DELC, /ALL, /EXE_CODE=CODE,, EXE_MESS=TELL

          To delete all the channel numbers stored in the array KILL_CHANS and to return all the invalid channel numbers to BAD_CHANS:

          FAS_DELC,CHANS=KILL_CHANS,INVALID=BAD_CHANS

        5. FAS_FFT

          6. PURPOSE:

          To calculate the FFT of channels between a specified time range and to return either the amplitude or phase or both. It also allows windowing operations.

          CALLING_SEQUENCE: FAS_FFT

          KEYWORDS:

          *CHANS:

          A one dimensional integer array containing the channel numbers to be Fourier Transformed. If it is not set, channel numbers will be extracted from the list of selected channels in memory. If an invalid channel number is specified, FAS_FFT will ignore it and carry on.

          EXE_MESS:

          Returns any messages from the program as it is executed.

          EXE_CODE:

          Returns values based on the execution of the program. If an error has occurred a negative value is returned.

          0: Operation successful.

          -1: ALPHA is not a floating point value.

          -3: CHANS is not an integer.

          -4: TIME_RANGE is not of the correct type.

          -5: TIME_RANGE does not have the right dimensions.

          -6: No channels in memory.

          -7: All channel numbers are invalid.

          VERBOSE:

          If this keyword is set, the procedure will display messages to the screen.

          INVALID:

          Returns channel numbers of any invalid channels that have been specified.

          TIME_RANGE:

          A two dimensional array that holds the time ranges over which the FFT is to be performed. The first column of the array must hold the start times and the second the finish times. Alternatively, the array can be one-dimensional with the start and finish times alternating. If all the time ranges are not specified then the last time range is replicated for the remaining channels. FAS_FFT will not accept an odd number of elements.

           

          AMPLITUDE:

          Set this keyword to calculate the amplitude of the cross power spectrum.

          PHASE:

          Set this keyword to calculate the phase of the cross power spectrum.

           

          DEGREE:

          If set, this will cause the phase to be output in degrees rather than in radians.

          HANNING:

          Set this keyword to use the Hanning window on the FFT.

          ALPHA:

          Set this value between 0.5 and 1.0 to manipulate the Hanning function. This keyword has no effect if HANNING is not set. The default value is 0.5.

          HAMMING:

          Use the Hamming window on the FFT. In fact the Hanning window with alpha set to 0.54 will produce exactly the same result.

          BLACKMAN:

          Use the Blackman window.

           

          EXAMPLES:

          To return the FFT of channels 1,2 and 5, and implement the Hanning

          window:

          FAS_FFT, CHANS=[1,2,5], /HANNING

          Perform the FFT on the same channels but specify the time ranges:

          FAS_FFT,CHANS=[1,2,5],TIME_RANGE=[[-0.5,0.5],[-1.0,1.0],[0,0]]

          OR

          FAS_FFT,CHANS=[1,2,5],TIME_RANGE=[-0.5,0.5,-1.0,1.0,0,0]

        6. FAS_INTG

          7. PURPOSE:

          To integrate a list of channels and create new channels in memory containing the results.

          CALLING SEQUENCE: FAS_INTG

          KEYWORD S:

          CHANS: Set this keyword to an integer array containing the channel numbers to be integrated.

          EXE_MESS: Set this keyword to return messages to EXE_MESS when an error takes place or if the operation is successful. If verbose is set, these messages are displayed to the screen.

          EXE_CODE: Set this keyword to return the execute code to EXE_CODE.

          1: Operation successful

          -3: No channels stored in list

          -4: All channel numbers are invalid

          -5: Time range is not of correct form-must be a floating point.

          array

          -6: Dimensions of time range are not correct.

          -7: CHANS is not of the right type, it must be a float

          or an integer

          VERBOSE: Set this keyword to display messages to the screen during execution of the procedure.

          INVALID_CHAN: Set this keyword to assign all the invalid channel numbers to INVALID_CHAN. If verbose is set these channel numbers are displayed to the screen.

          TIME_RANGE: Set this keyword to specify the time range for integration. It must be set to either a one dimensional array with the start and finish time or a two dimensional array in which the number of rows is equal to the number of channels requiring integration. If only a one dimensional array is given, all the channels are integrated over that time range.

          N.B. If time ranges lie outside the time range of the channel then integration takes place over its entire time base.

          REPLACE: Channels can be selected in FAS to be processed. These channels are stored permanently in FAS. If replace is set, newly created channels from the integration will replace the channels stored in memory.

          N.B. : If CHANS is not set the program integrates the channels selected in the process window. If no channels have been selected then the procedure ends.

          EXAMPLES:

          To integrate channels 1,2,4,10,13,3 & 11:

          FAS_INTG, CHANS=[1,2,4,10,13,3,11]

          To integrate channels whose channels numbers are stored in an array CHAN_ARR. Displaying the error messages and assigning any invalid channel numbers to INVALID_CHAN:-

          FAS_INTG, CHANS=CHAN_ARR,/VERBOSE,$

          INVALID_CHAN=INVALID_CHAN

          To integrate channels as above but between a time range of 1 and 2 sec.:

          FAS_INTG,CHANS=CHAN_ARR,$

          TIME_RANGE=[1,2],/VERBOSE,INVALID_CHAN=INVALID_CHAN

          To integrate different channels between different time ranges:

          FAS_INTG,CHANS=[1,2],TIME_RANGE=[[0.1,0.5],[1,1.3]]

          To integrate channels that have been selected in the process window and to replace the list with the newly created channels:

          FAS_INTG,/REPLACE

        7. FAS_LIST

          8.  

          PURPOSE: To obtain a shot list or signal list.

          CALLING SEQUENCE: FAS_LIST

          KEYWORDS:

          *FILE:

          Set this keyword to the string specifying the full filename (including disk and directory) from which to obtain a shot or signal list.

          SHOT_LIST:

          Set this keyword to the variable to receive the shot list. If the file is an invalid shot list file a null scalar string is returned.

          SIGNAL_LIST:

          Se this keyword to the variable to receive the signal list. If the file is an invalid signal list file a null scalar string is returned.

        8. FAS_MODIFY_CHAN

          9. PURPOSE: To create a new channel directly or by modifying an existing channel.

          CALLING SEQUENCE: FAS_MODIFY_CHAN

          KEYWORDS:

          CHANS:

          Set this keyword to the channel number to be modified. If not assigned a new channel is created. For new channels all keywords must be set, except for error message keywords and either [TMIN,TMAX, TSAMS,TINT] or TIME_BASE

          SHOT:

          Set this keyword to a long integer to specify the shot number for the channel.

          NAME:

          Set this keyword to a string to specify a new name for the channel.

          DATA:

          Set this keyword to a float array to specify the data for the channel.

          TMIN:

          Set this keyword to a float array to specify the minimum time of the time domains

          TINT:

          Set this keyword to a float array to specify the time interval of the time domains.

          TSAMS:

          Set this keyword to a array of long integers with dimension equal to the number of time domains to specify the number of time samples in the domain.

          TMAX:

          Set this keyword to a float array to specify the maximum time in each time domain.

          TUNITS:

          Set this keyword to a string to specify the time units.

          Note: The number of elements in the time keywords( i.e., TMIN, TMAX, TINT, TSAMS) must be the same, and the number of time points must equal the number of data points. If one time KEYWORD is set they all must be set.

          TIME_BASE:

          Set this keyword to a float array that holds the time points. This can be used instead of all the time keywords. The TUNITS keyword still has to be specified though. The number of time points must be equal to the number of data points.

          CALFAC:

          Set this keyword to a float to specify the calibration factor for the channel.

          DUNITS:

          Set this keyword to a string to specify the data units.

          EXE_CODE:

          Set this keyword to return the error code for the execution of the procedure.

          0: Operation successful

          -1: All the time information keywords do not have the same dimensions.

          -3: Invalid channel number.

          -4: The time information is not compatible with the DATA

          -5: The time information is not compatible with the DATA

          -6: Insufficient information to create a new channel

          EXE_MESS:

          This keyword retrieves the above messages when set.

          VERBOSE:

          If set then all the above messages are displayed to the IDL command line.

        9. FAS_PLOT_OPTIONS

          10. PURPOSE:

          To allow a programming interface to the plot options windows in FAS

          CALLING SEQUENCE: FAS_PLOT_OPTIONS

          KEYWORDS:

          *WINDOW:

          An integer array that holds the window numbers of all the windows whose plots are to be modified. Invalid window numbers are ignored. This keyword must be specified.

          PANEL:

          An integer array containing the panel number of the panels to be modified. Invalid panel numbers are ignored.

          ELEMENT:

          An integer array containing the element number of the traces to be modified. The element numbers range from 1 to the number of traces in window.

           

          ALL_POINTS:

          Set this keyword to a non-zero value to plot all the points in the data set.

          COLOR:

          Set this keyword to the index of the color table to be used for the trace.

          LINESTYLE:

          This keyword indicates the style of the lines used to connect data points.

          It is identical to the LINESTYLE keyword to PLOT in IDL.

          Index Linestyle

          0 Solid

          1 Dotted

          2 Dashed

          3 Dash Dot

          4 Dash Dot Dot Dot

          5 Long Dashes

          LOADCT:

          This keyword is set to an integer which then becomes the color table for each window specified. This is identical to the LOADCT procedure in IDL.

          NSUM:

          Set this keyword to the number of adjacent points to average to obtain a plotted point. This is identical to the NSUM field in !P.

          POINTS:

          Set this keyword to the number of points to be plotted. Setting this value to zero suppresses plotting of the data set.

          PSYM:

          The symbol used to mark each data point. Normally, PSYM is 0, data points are connected by lines, and no symbols are drawn to mark the points. Set this keyword, to the symbol index shown below to mark data points with symbols.

          Value Plotting Symbol

          1 Plus Sign

          2 Asterisk

          3 Period

          4 Diamond

          5 Triangle

          6 Square

          7 X

          8 User-defined. See USERSYM procedure in IDLHELP.

          9 Undefined

          10 Histogram mode.

          This keyword is identical to the PSYM keyword to PLOT in IDL.

          SYMSIZE:

          Specifies the size of the symbols drawn when PSYM is set. The default size is 1.0 produces symbols approximately the same size as a character.

          This keyword is identical to the SYMSIZE keyword to PLOT in IDL.

          [XY]CHARSIZE:

          This keyword is set to a floating point value. A CHARSIZE of 1.0 is normal. This is identical to the CHARSIZE keyword to PLOT in IDL.

          [XY]GRIDSTYLE:

          The index of the linestyle to be used for plot tickmarks and grids (i.e., when

          [XY]TICKLEN is set to 1.0). Refer to LINESTYLE for list of indices.

          [XY]LIN:

          Setting this keyword to a non-zero value changes the axis to linear scaling. This overrides the [XY]LOG keyword.

          [XY]LOG:

          Setting this keyword to a non-zero value changes the axis to logarithmic scaling.

          [XY]MARGIN:

          A 2-element array specifying the margin on the left (bottom) and right (top) sides of the trace area, in units of character size.

          [XY]MINOR:

          The number of minor ticks. Setting XMINOR to 0 autovalues the number of minor ticks. Setting XMINOR to -1 suppresses minor ticks. This is identical to the [XY]MINOR keyword to PLOT in IDL.

          [XY]RANGE:

          The desired data range of the axis, a 2-element vector. The first element is the axis minimum, and the second is the maximum. IDL will frequently round this range. This override can be defeated using the [XYZ]STYLE keywords. Setting this keyword also overrides the [XY]_RANGE keyword.

          This is identical to the [XY]RANGE keyword to PLOT in IDL.

          [XY]STYLE:

          Allows specification of axis options such as rounding of tick values and selection of a box axis. Each option is encoded in a bit. Each option is described below.

          Bit Value Description

          0 1 Force exact axis range.

          1 2 Extend axis range.

          2 4 Suppress entire axis

          3 8 Suppress box style axis

          Multiple selections are allowed. So for example to set the X - axis to exact range with no-axis set XSTYLE = [1, 0, 1, 0]

          This is NOT identical to the [XY]STYLE keyword to PLOT in IDL, as although the same options are set, [XY]STYLE must be an integer array of four elements, with each element set to 1 or zero.

          [XY]THICK:

          This keyword controls the thickness of the lines forming the axis and tick marks. A value of 1.0 is the default. This is identical to the [XY]THICK keyword to PLOT in IDL.

          [XY]TICKLEN:

          This keyword controls the lengths of tick marks (expressed in normal co-ordinates , i.e. 0.0 to 1.0) for the individual axes. This is identical to the [XY]TICKLEN keyword to PLOT in IDL.

          [XY]TITLE:

          A string that contains a title for the specified axis. If the keyword is set to ‘DUNITS’ or ‘TUNITS’ then the axis title will be the data or time units of the channel . This keyword is identical (except for the case mentioned above) to the [XY]TITLE keyword to PLOT in IDL.

          [XY]MODE:

          This keyword is used to set the method of autoscaling based on the channel(s) that is/are being plotted.

          Value Description

          0 Universal Range is selected

          1 Individual Range is selected.

          Universal range finds the minimum and maximum value of all the channels (time if XMODE, data if YMODE) to be plotted in the same ‘Window’, and sets the [XY]RANGE values automatically.

          Individual range finds the minimum and maximum value of the specific channel to be plotted, and sets the [XY]RANGE values automatically.

          If the [XY]RANGE keyword is specified then it overrides [XY]MODE.

          [XY]TICKS:

          A floating-point array with three elements. The first specifies the first tick value. The second element gives the last(/cut off) tick value. The third element gives the increment, between tick values. If this keyword is set explicitly to 0 then the ticks are autoscaled.

           

        10. FAS_POLYNOMIAL

          11. PURPOSE:

          To add channels with the same time base raised to the given index together with coefficients and to store the result as a new channel in memory. The formula this program uses is:

          Result=c(0)+c(1)X(0)^e(0)+c(2)X(1)^e(1).....c(n)X(n-1)^e(n-1)

          Where: c(i) = Coefficient of the ith channel (COEFF(i)),

          X(i) = the ith Channel &

          e(i) = Exponent of the ith channel (EXPO(i))

          CALLING SEQUENCE: FAS_POLYNOMIAL

          KEYWORD PARAMETERS:

          *CHANS:

          Set this keyword to an integer array containing the channel numbers.

          EXE_MESS:

          Set this keyword to return messages to EXE_MESS when an error takes place or if the operation is successful. If VERBOSE is set, these messages are printed to the screen.

          EXE_CODE:

          Set this keyword to return the run flag to EXE_CODE.

          1: Operation successful.

          -1: CHANS must be an integer or a floating point value.

          -2: COEFF must be an integer or a floating point.

          -3: EXPO must be an integer or a floating point.

          -4: No channels have been selected.

          -5: All channel numbers are invalid.

          -6: Error has occurred in FAS_INTERPOL

          (see FAS_INTERPOL help).

          -7: Channels do not have a common time range

          -8: All channels do not have the same time base.

          -9: NORM_FACTOR must be an integer or a floating point value.

          -10: NORM_FACTOR must have only one element.

          -11: Channel cannot be normalised with respect to the

          average because the total of channel is zero.

          -12: Error has occurred in FAS_DELC (see FAS_DELC for

          help).

          -13: N_OUTPUTS must be of integer type.

          -14: Number of outputs is greater than the number of

          channels.

          -15: OFFSET is not of integer or floating point type.

          -16: TIME_RANGE is not of the correct type

          -17: TIME_RANGE does not have the right dimensions

          -18: NORM_FACTOR cannot be zero

          VERBOSE:

          Set this keyword to display messages on he screen during

          execution of the procedure.

          INVALID_CHAN:

          Set this keyword to assign all the invalid channel numbers to INVALID_CHAN. If verbose is set these channel numbers are displayed on the screen.

          COEFF:

          This keyword must be a floating point or an integer. It must be an array. If the number of elements of the coefficients is less than the number of channels then the last element is repeated for the remaining number of times. If the array is too large then only the first N coefficients are taken where N is the number of channels.

          EXPO:

          This keyword must be a floating point or an integer array. The defaults for index are identical to those of COEFF.

          N_OUTPUTS:

          Set this keyword to enable multiple outputs. If this is a single number then the channels are split up by this number to ensure that as many outputs are obtained.

          For example if we had 10 channels and N_OUTPUTS was set to 2 then the outputs would be [5,5], i.e. the first 5 channels would be added together to give one output and the second 5 channels would be added together to give a second output. Choosing 20 channels and 6 outputs, we get [4,4,3,3,3,3] which has 6 elements and a total of 20. Choosing 25 channels and 6 outputs, we get [5,4,4,4,4,4].

          OFFSET:

          This must be a floating point or an integer array. It’s defaults are similar to that of COEFF. It is made to equal the number of outputs. Therefore one has an offset for each output.

          NORMAL:

          Set this keyword to normalize the result to a number between 0 and 1. This keyword has preference over the two below.

          NORM_FACTOR:

          Set this keyword to a floating point or an integer. The result is then normalised using the NORM_FACTOR. This keyword has preference over the keyword below.

          NORM_AVE:

          Set this keyword to normalize the result by the average of the result.

          AVERAGE:

          Set this keyword to average the result of the channels.

          SUB_AVE:

          Set this keyword to subtract the average of the result from the result.

          TIME_RANGE:

          This keyword can only be set with the SUB_AVE keyword. If it is set on its own it will have no effect on the result. Set this keyword to calculate the average between a time range. It must be a 2 element array, the first element being the start time and the second being the finish time.

          EXAMPLES:

          To add channels 1,2,5,7 & 11:

          FAS_POLYNOMIAL, CHANS=[1,2,5,7,11], COEFF=[1] or

          FAS_POLYNOMIAL, CHANS=[1,2,5,7,11]

          To add channels 1 & 2 with an offset of 100:

          FAS_POLYNOMIAL, CHANS=[1,2],OFFSET=100

          To add 2*(channel 4)^2 and 5*(channel 3)^3 plus 20:

          FAS_POLYNOMIAL, CHANS=[4,3], COEFF=[2,5], EXPO=[2,3],$

          OFFSET=20

          To do the same as above but to return messages:

          FAS_POLYNOMIAL, CHANS=[4,3], COEFF=[2,5], EXPO=[2,3],$

          OFFSET=20, /VERBOSE

          To add channels 1,2,3,4 & 5 together and normalize the result:

          FAS_POLYNOMIAL, CHANS=[1,2,3,4,5], /NORMAL

          To add channels 2,4,5,6,7 with coefficients 2,2,3,4,4 and to average them, and then normalize the result to 100:

          FAS_POLYNOMIAL, CHANS=[2,4,5,6,7], COEFF=[2,2,3,4,4],$

          NORM_FACTOR=100

          To do the same as above but to normalize the result using the average:

          FAS_POLYNOMIAL,CHANS=[2,4,5,6,7],COEFF=[2,2,3,4,4],$

          /NORM_AVE

          To square channels 1,2,3,4,5 individually:

          FAS_POLYNOMIAL,CHANS=[1,2,3,4,5],EXPO=2,N_OUTPUTS=5

          To square