WSPEX'S USERS MANUAL FOR BATSE SOLAR FLARE ANALYSIS Written by Lanny Thompson, Arkansas State University August 1995 TABLE OF CONTENTS INTRODUCTION ABOUT WSPEX................................................ GETTING STARTED GETTING TO WSPEX........................................... AN OVERVIEW OF THE WIDGETS................................. GENERAL OVERVIEW SELECTING DATA.............................................. SELECTING AN OPTIONAL DRM.......................... SELECTING THE BATSE INSTRUMENTS.................... CHOOSING A FLARE ARCHIVE NUMBER.................... PREVIEWING THE DATA FILE........................... CHOOSING A DETECTOR................................ DISPLAYING OPTIONS................................. TIME HISTORY............................................... DISPLAYING A LIGHT CURVE........................... Single or multi-trace...................... Observing the detector cosines............. ADJUSTING THE TIME PROFILE......................... Zooming in time............................ Changing the y-axis........................ scale.............................. units.............................. range.............................. SELECTING ENERGY CHANNELS.......................... Selecting the channels..................... Adjusting the scale........................ DEALING WITH BACKGROUND............................ Subtracting Background..................... Clearing Background........................ TIME INTERVALS..................................... Selecting and displaying................... Clearing................................... SPECTRAL PLOTS............................................. DISPLAYING A SPECTRAL PLOT......................... Background................................. Counts..................................... Photons.................................... ADJUSTING THE SPECTRAL PLOTS....................... Adjusting the x and y-axis................. BINNING............................................ Selecting.................................. Clearing................................... DISPLAYING THE CURRENT OPTIONS..................... FITTING.................................................... CHOOSING A FIT MODEL............................... SELECTING VALID ENERGIES........................... THE FIT PARAMETERS................................. Changing and viewing....................... Freeing and fixing parameters.............. FITTING AND PLOTTING............................... Performing the fit......................... Observing the chisquare.................... SUMMARY FILES.............................................. Saving..................................... Restoring.................................. POSTSCRIPT FILES (SENDING A PLOT).......................... Saving..................................... Printing................................... Labeling the x and y-axis.................. LEAVING WSPEX.............................................. INTRODUCTION ABOUT WSPEX WSPEX is an IDL based program designed by Richard Schwartz that evaluates solar flare and burst data collected from a variety sources. The program enables the user to evaluate the light curve of a given flare or burst. WSPEX also allows spectral fits over a desired time interval and energy range to be displayed and fitted against a variety of models. Print-outs of these plots can be produced in several different scales and labels in WSPEX, and saved as postscript (.PS) files. All these functions, and being able to perform them quickly, are made possible by the program's use of WIDGETS, making WSPEX very easy to use. Although WSPEX can handle various collection instruments and types of data, this manual only describes the methods used to analyze solar flares gathered by the BATSE instrument cluster on the Compton Gamma Ray Observer. GETTING STARTED GETTING TO WSPEX To run WSPEX simply log on to the SDAC network from a workstation or Xterminal capable of running Xwindows and IDL graphical programs. From SDAC call the directory where all files made in WSPEX will be saved or where files have already been saved and will be used in the present WSPEX work session. Once the desired directory is selected, type IDL from the $ prompt. The network will respond by compiling some core IDL modules to start IDL, which should end in an IDL prompt ( IDL> ). From the IDL prompt, type WSPEX; IDL will then compile some WSPEX modules and start WSPEX. AN OVERVIEW OF THE WIDGETS When WSPEX is first started, four windows will appear. The bottom two windows will appear first. (NOTE: NOW AND THROUGHOUT THE REST OF THE MANUAL, REFERENCES MADE TO THE LOCATION OF ANY WINDOWS (OR WIDGETS) ARE THE DEFAULT LOCATIONS THE WINDOWS HAVE AT START UP) The bottom two windows display information and provide choices of actions the user can take. These two windows are labeled "INFO BOX" and "SPEX CONTROL PANEL". The upper two windows display the graphical plots WSPEX is capable of performing. They are known as the TIME HISTORY WINDOW and SPECTRAL WINDOW. Combined, these four boxes comprise the bulk of the WSPEX program; however, there is a fifth part of the WSPEX program. The console, or terminal, window used to run WSPEX also gives useful information about WSPEX to the user. It is these five boxes that form the WSPEX program. The lower right window is the SPEX CONTROL PANEL. It is from this box that most actions are made. These actions include: the choice of data to be used, the plotting of light curves and spectral fits, and the type of fit model to use. Other actions can be used to change plots or fits, producing a plot that meets the user's specifications. These functions are available by activating one of the two rows of buttons, labeled ACTION and OPTIONS. Selecting a button will give another menu giving a choice of actions or other menus to choose an action from. Most of the primary functions, dealing with BATSE solar flare analysis, of the SPEX CONTROL PANEL will be discussed in the GENERAL OVERVIEW section. The INFO BOX is the lower left window. As the name implies, the INFO BOX displays information about the WSPEX program and settings. Some of the information the INFO BOX is capable of displaying includes: current settings, special options chosen, detector cosines, and important data relating to the solar flare chosen. The TIME HISTORY window, located in the upper left, is where the light curve is displayed. It also from this window that the light curve can be manipulated to meet the user's requirements. Examples of these manipulations include the subtracting of background, and zooming in time. Another important feature of the TIME HISTORY window is interval (intervals) may be selected from the window plot itself. The upper right area contains the SPECTRAL WINDOW display. The SPECTRAL WINDOW box offers four types of plots: COUNTS, PHOTONS, CALIBRATION CHECK, and BACKGROUND. All these plots, except for the CALIBRATION CHECK plot, will be discussed in the GENERAL OVERVIEW SECTION. The user can also fit the data with a given model, which is displayed with the current plot in the SPECTRAL WINDOW box. Other forms of direct user interaction with the SPECTRAL WINDOW display include: the selection of an energy range, directly from the plot window, to fit and the BINNING of points. The last window available for use is the console or terminal that runs IDL and WSPEX. This window is located in the background behind the other windows. Although seldom used directly by the user once WSPEX is started, the console does display some vital information important to the user. It is from this window that the value of the Chi Square and fit parameters can be viewed, while the fit calculations are running or at the end of the fit. Another use of the console is it may help the user return to WSPEX, after an unfortunate halt in the program or program termination, without losing current data. GENERAL OVERVIEW SELECTING DATA This section of the general overview deals with the selection of the data instruments and the specific events that WSPEX is to analyze. WSPEX is capable of handling solar data from a variety of sources; however, this overview deals only with the BATSE source. The selection of the source and event (individual flare) all takes place within the SPEX CONTROL PANEL, which makes the task very easy to perform. Once experienced, a user shouldn't have any problem finding and using a specific flare from the BATSE database rather quickly. SELECTING AN OPTIONAL DRM The first step in the data selection process is to choose a Detector Response Matrix or DRM. This may be an optional choice, since WSPEX has a Default DRM that it uses if no other one is selected. The default DRM should be the better DRM to choose; however, other DRMs could be upgrades of the existing default DRM that haven't yet replaced the old DRM. In this case, a changing of the existing default DRM to a better DRM is a good choice. There are also incidents where a special DRMs are designed to handle specific cases. If the user is dealing with data that falls into this category, a special DRM should be selected to get the best results possible. NOTE: This manual does not provide details on these special cases or DRMs. To choose an upgraded default matrix DRM or a development DRM, access the SPEX CONTROL PANEL by clicking the left mouse button within the SPEX CONTROL PANEL window (NOTE: this should highlight the window). Next, select the SPECTRAL FITS button from the OPTIONS row. After the button is activated, the OPTIONS:SPECTRAL FITS menu will appear; from the menu select the RESPONSE MATRIX OPTIONS option. This choice should display another menu with a list of functions to choose from. From this menu choose the DEVELOPMENT DRM function. WSPEX should respond by building the developmental DRM. NOTE: The developmental DRM function may not exist in the final version of WSPEX; therefore, this procedure could be obsolete. If the function doesn't exist, the default matrix should be the DRM to use except in special cases. SELECTING THE BATSE INSTRUMENTS Before any flare recorded by the BATSE detectors can be analyzed, WSPEX must first be set to view BATSE files. The first step in choosing the BATSE instruments is to activate the SPEX CONTROL PANEL. This is done by clicking the left mouse button within the SPEX CONTROL PANEL WINDOW. Next, the SPECIAL button from the OPTIONS row is selected. WSPEX will respond by displaying the options: special menu. From this menu select the DATA TYPE option, which should display another menu containing a list of instrument sets. The list should read (from top down): BATSE, YOKOH, SMM, HIREX. The next step is to select the BATSE option from the list. After selecting the BATSE option, another menu will appear. At this menu, choose the SHER AND SHERB setting. WSPEX is now set properly. NOTE: This program only deals with the SHER and SHERB (high resolution) setting. CHOOSING A FLARE ARCHIVE NUMBER One of the most important steps in choosing the data is selecting a flare archive number. This number is the label given to an individual flare event. It is less confusing for the user if the flare archive number is entered after the data type has been selected. To select a flare, activate the SPECIAL widget button from the OPTIONS row of the SPEX CONTROL PANEL. The selection will display the options: special menu. Next, select the EVENT ID option from the options: special menu, which will cause the event id menu to be displayed. From this display the choose the function labeled "ARCHIVE #". This choice will display another widget, labeled "Select A Number", that is comprised of five columns of numbers, ranging from 0 to 9. These columns help the user compose the digits of a flare archive number. To compose any flare archive number, click on the number in each column that relates to each digit in the flare archive number. For example: if the flare archive number is 03030, the user would click the zero in the ones column, a three in the tens column; and so forth. While entering the number, the user should notice that there is a panel above the columns, displaying the digits as they are selected. Once all the numbers are entered and the above panel displays the correct value, select the ready button (lower left) on the widget. This will remove the window and set WSPEX to ready the flare chosen. If the select a number window is selected and displayed accidentally or if the user doesn't want to select a flare, click on the CANCEL button inside the window. WARNING: Closing the "select a number" window, or any other window in WSPEX, by other means than the one listed, could interrupt the WSPEX program. PREVIEWING THE DATA FILE After a flare has been chosen, it is sometimes useful to preview the flare data before selecting a detector or plotting a light curve. The preview of the flare data file gives useful information in helping to make some further choices towards the treatment of the flare as well. Examples of the type of information given include: The detector cosines, detectors available, and the lower edge pulse height for the detectors. This information is displayed inside the INFO BOX window. To preview the data file of a flare (a flare must be already be selected), select the SPECIAL button from the ACTIONS row of the SPEX CONTROL PANEL. This action will display the actions: special menu. Next, select the PREVIEW DATA FILE function from this menu. WSPEX will now clear the actions: special menu, perform the preview data file procedure, and display the information inside the INFO BOX. CHOOSING A DETECTOR BATSE is an instrument cluster composed of eight detectors with different positions and locations on the Gamma Ray Observer. Since they are at different locations, and angles, from the sun; every detector gets a different reading for each flare. These different readings lead to only a few of the detectors getting good data from an event. Therefore, a proper detector will have to be selected before a light curve can be displayed correctly. (Note: In the event that no detector is selected the default detector is chosen, which in most cases will not be the one desired for the particular event.) Several factors must be accounted for in the choice of a good detector. Examples of these criteria include: the position of the detector to the event (detector cosine), the number of counts available, and the amount of "pile-up" present. This manual does not give instructions on selecting a proper detector and is written on the basis that the user will determined the detector needed prior to starting WSPEX. To choose a detector for a selected flare, activate the WPSEX CONTROL PANEL. Next, select the SPECIAL button from the OPTIONS row, which will display the options: special menu. From this menu select the DETECTOR # option. This action displays a column of numbers ranging from 0 to 7; these are the detector ids. Finally, select the proper id number for the flare already selected. WSPEX is now set for the proper detector. DISPLAYING OPTIONS Displaying the user's current options is an important feature of the INFO BOX. This action provides a useful safeguard, by showing the user what WSPEX's current settings are. This also saves the user valuable time, because options set incorrectly can be found quickly from the display before an incorrect light curve is accidentaly produced. Some of the options displayed include: the detector id, data type, detector cosine (if available); along with other options of importance to the user. NOTE: This procedure can be performed at any time while running WSPEX. The first step in displaying the options is to select the SPECIAL widget button from the ACTIONS row of the SPEX CONTROL PANEL. This action will display the actions: special menu. Once the menu is available, select the SHOW CURRENT OPTIONS action (first in the list). This selection updates the INFO BOX, which should now show WSPEX's current settings, and clears the actions: special menu. TIME HISTORY DISPLAYING A LIGHT CURVE The first step in actually viewing the data is to display the light curve. The light curve appears within the TIME HISTORY window and shows the user the amount of counts per second (or with other units) on the y-axis recorded by the detector during a lapse of time on the x-axis. The light curve can show the counts from four energy channels, that the user may select, or from a single energy range. These two methods of displaying the light curve are referred to as multi-trace and single-trace respectively. A single or multi trace light curve is produced by first activating the SPEX CONTROL PANEL. Next, select the TIME HISTORY button from the ACTIONS row. Once the actions: time history menu is displayed, select the PLOT LIGHT CURVE (READ) option. This will prepare WSPEX to read the data file and plot the light curve. The last action should also display another menu allowing two choices: ONE TRACE or MULT-TRACE. To plot a single trace, choose the ONE TRACE option; for a multi-trace plot, choose the MULTI-TRACE option. WSPEX will respond by reading the data file and performing a series of calculations on the data, which will result in the display of the chosen light curve. While WSPEX is making the necessary calculations to show the light curve, useful information about the flare and light curve is displayed in the INFO BOX window. One of the most useful facts displayed is the detector cosines and the detectors available for a given flare. This information given is similar to the information provided by previewing the data file. Therefore, the information given during the processing of the light curve is another way for the user to make sure a good detector has been chosen and other settings are correct. ADJUSTING THE TIME PROFILE When the light curve is first displayed, it may not be set in the way that the user prefers. For example: the user may want to change the y-axis units or zoom in on a particular region of time where the majority of the flare is located. Fortunately, WSPEX allows the user to perform the procedures mentioned above. WSPEX also allows other options, such as selecting the energy channels to plot; which set the light curve to the user's specifications. Note: For most adjustments to the light curve to take place, the light curve must be retraced by following the procedures listed in the previous section. One of the main actions performed when the light curve is first displayed is the process of "zooming in". This action is required, because the actual flare usually only comprises a small section of the time interval first displayed. Therefore, it is necessary to zoom in time and enable the flare to compose the majority of the time interval viewed. (Note: If background intervals haven't been selected, it is necessary to keep a an area of background, before and after the actual flare, to be subtracted off.) Another reason for zooming in is certain sections of the flare need to be viewed so smaller time intervals may be selected for fitting. To zoom in on a specific area, select the TIME HISTORY button from the ACTIONS row of the SPEX CONTROL PANEL. Next, choose the ZOOM IN TIME function from the actions: time history menu. Once selected, a window will appear labeled "Interval Selection Mode". The window has two options to choose from: an option to enter the zoom limits non-graphically and an option to enter the limits graphically. From the window select the GRAPHICAL INPUT option. (NOTE: This manual provides information for the GRAPHICAL INPUT option only.) This action should remove the window and ready the TIME HISTORY window for selection of limits. From the TIME HISTORY window, use the cross-hairs icon to select the limits (clicking where a limit is to placed). A vertical limit line will appear after each of the two selections is made and the INFO BOX will display the values of each limit. Once both selections are made, move the icon outside of the time history window and the area within the vertical lines will be replotted to fit the full window. Another form of adjusting the time profile to suit the user's needs is to change the scale along the y-axis. This action is performed by selecting the TIME HISTORY button from the OPTIONS row. Once selected, choose the Y-AXIS option from the options: time history menu. This action will provide another menu offering the choice of two options: LINEAR of LOG. From this menu select the scale the y-axis should be in. This selection will set WSPEX to scale the y-axis accordingly. However, the user must replot the light curve for the changes made to take place. The units can also be changed on the y-axis to meet user's specifications. To change the units, select the TIME HISTORY widget button from the OPTIONS row of the SPEX CONTROL PANEL. Next, select the Y UNITS option from the options: time history menu. This selection should display two sets of units to choose from: counts per second and counts per second per square centimeter per kilo-electron volt. The user must now select the units desired, which will set WSPEX to the proper units. The change can be viewed by retracing the light curve. The y range will sometimes need adjusting to incorporate, or cut-off, sudden spikes within a flare. The first step in adjusting the y range is to select the TIME HISTORY button from the OPTIONS row of the SPEX CONTROL PANEL. Next, choose the YRANGE function from the options: time history menu. This action will remove the present menu and display a window labeled "MODIFY OPTION". This window will have two panels, numbered 0 and 1, both labeled "YRANGE FOR TIME HISTORY PLOT". The 0 panel is where the starting value of the y-axis is entered and the 1 panel is where the ending value of the y-axis is entered. (NOTE: If on a log scale the starting and ending values of the y range will be rounded by WSPEX to the nearest order of ten.) After entering the desired range for the y-axis, select the done button. The changes are now set into the WSPEX program and can be viewed by retracing the light curve. SELECTING ENERGY CHANNELS After a plot is displayed, the user may decide the current energy channels aren't satisfactory. Therefore, WSPEX has the option that allows the user to switch any of the current channels and adjust the scale of their display; however, this option is only available on a multi-trace plot. Although the action does have this limitation, the amount of multi-trace plots over a single-trace a typical user will perform makes the selection of specific channels worth knowing. To switch the plot to a desired energy channel or channels, select the TIME HISTORY button from the OPTIONS row of the SPEX CONTROL PANEL. From the options: time history menu, choose the ENERGY BANDS (MULTI-TRACE) function. This function will display a "Modify Option" window composed of 8 panels, numbered 0 to 7, labeled "Time History Band Multi-Trace =>". These panels are paired off in numerical order to hold the minimum and maximum range of the four channels; therefore, the first pair of numbers holds the values for the first channel displayed. The first panel of each pair holds the minimum range, while the last panel holds the maximum. To change any channel, replace the numbers in the corresponding set of panels with the desired values. Once all the channels are adjusted accordingly, select the done button from the modify option window. The next light curve displayed will be plotted with the new energy ranges. After new energy channels are chosen or when the light curve is first displayed, it may be necessary to adjust the scale of a certain energy channel to get a better plot. This is performed by first selecting the TIME HISTORY button from the OPTIONS row of the SPEX CONTROL PANEL. From the menu select the SCALE FOR BANDS function. This function will display a "Modify Option" window comprised of 4 panels. Each panel holds the scaling factor for an individual channel. To adjust the scaling of a channel, replace the existing value with the desired scaling value. After all changes have been made, select the DONE button from the "Modify Option" window. Once the light curve is retraced, the channels will be scaled with the new settings. DEALING WITH BACKGROUND Background is apparent in any initial plot of a light curve. In fact, it will usually comprise the bulk of the first light curve displayed, while the actual flare itself will comprise a substantial lesser amount. Therefore, it is essential for the user to eliminate as much background possible from the actual flare to help insure that actual data is being analyzed instead of noise. To select background intervals to be subtracted off, select the TIME HISTORY widget button from the ACTIONS row of the SPEX CONTROL PANEL. Once the options: time history menu is displayed, choose the BACKGROUND option. This selection should display another menu offering several choices for handling the background. From this menu select the SELECT INTERVALS action. This action will remove the current menus and display a set of intervals on the light curve. This action also displays a window labeled "BACKGROUND MODEL FOR ENERGY BAND 3000" that asks if the current intervals are acceptable. In almost all cases, the intervals chosen by WSPEX will not be acceptable and the NO button will be chosen. However, if the background seems correct, select the YES button and WSPEX will subtract off the chosen background. If the background is not acceptable, select the NO button and WSPEX will wait for the intervals to be entered in graphically. (NOTE: Either choice, Yes or NO, will remove the previous window.) To enter the intervals in graphically, place the cross-hairs where each interval limit (remember is takes two limit lines to make an interval) should go. It is usually better for two selected instead of one; one preceding the flare and the other following the flare occurrence. Once the interval (intervals) are chosen, move the cursor outside of the time history window. This will display a Cursor Controls window. (NOTE: IF the cursor is inadvertently removed from the time history window before all the intervals are chosen, select the CONTINUE... button from the CURSOR CONTROLS WINDOW.) From the Cursor Controls window, select the done button. Once selected, WSPEX will subtract off the background and display the newly adjusted light curve automatically. To clear background intervals that were incorrectly chosen, follow all the previous instruction given above up to selecting the background option from the actions: time history menu. Once the background option is selected and its menu is displayed, choose the CLEAR BACKGROUND function. This function will enable WSPEX to clear the current background intervals and redisplay the light curve before the background intervals were chosen and subtracted. TIME (FIT) INTERVALS Time intervals are the sections of a light curve that serve as the source of data for any spectral plots or fits performed. The size and location is an important factor in selecting a time interval. It is these two criteria that determine how much reasonable data can be discriminated from the background. Therefore, the user should practice and attempt to reproduce data from well documented flares (with recorded time intervals). This practice will help the user develop an ability to adequately select reasonable time intervals from any given flare. NOTE: The directions given in this manual are for a single discrete time interval. Although WSPEX allows for multiple intervals, the instructions for selecting multiple intervals are not given. The first step in selecting intervals is to have the desired selection displayed within the current section of the light curve. The future interval needs to be displayed large enough so it may be selected directly from the plot window. This usually requires a zoom in time for a better view of the proposed interval. The next step is to select the TIME HISTORY button from the ACTIONS row of the SPEX CONTROL PANEL. Once selected, choose the FIT INTERVALS option from the actions: time history menu. This action will display the fit interval menu, which will offer three choices: SELECT, DISPLAY, or CLEAR. Next, choose the SELECT function. WSPEX will respond by clearing the present menus and displaying the "Interval Selection Mode" window. This is the same window displayed when attempting to zoom in time and the user must make the same selection, which is selecting the GRAPHICAL INPUT button. This action will remove the window and display a new one labeled "Interval Selection". This window lets the user pick the type of fit interval WSPEX is supposed to use. From this window, select the BOUNDARIES FOR DISCRETE INTERVALS function. This action clears the window and allows the user to select that type of interval from the time history window. Now the interval can be selected directly from the light curve. The method for selecting the fit interval from the light curve is the same procedure as selecting background or zooming in time. To select the interval lines move the cursor to where a desired limit boundary should be and click the mouse button. Interval lines should appear after each boundary is selected. Once the two lines are displayed, move the cursor off the time history window. This will display the Cursor Controls window, where the DONE button is selected. The interval is now selected and will be used by WSPEX to perform spectral fits. Viewing the fit intervals prior to actually working with the data is an essential step, since the actual boundaries will be slightly different than the ones chosen. To display the fit intervals, repeat the procedures for selecting a time interval until the fit interval menu is displayed. Next, select the DISPLAY function. This action will display the actual boundaries that WSPEX uses onto the present light curve. If the boundaries are acceptable, continue with the spectral analysis. However, unacceptable boundaries will have to be cleared and reselected before continuing. To clear an unwanted fit interval, repeat the previous procedure until the fit intervals menu is displayed. Next, select the CLEAR function. This action will clear the present interval from WSPEX. NOTE: Before selecting a new interval, retrace the light curve so all previous lines are cleared from the display. SPECTRAL PLOTS DISPLAYING A SPECTRAL PLOT After a fit interval is selected, any of the four available spectral plots can be displayed by the spectral fits window (NOTE: The BACKGROUND plot is available for display after background is subtracted from the light curve.) The four types of spectral plots are known in WSPEX as: COUNTS, BACKGROUND, CALIBRATION CHECK, and PHOTONS. Each of these spectral plots will be reviewed except CALIBRATION CHECK, along with instructions on displaying each plot, in the following paragraphs. The Background plot is a display of the currently subtracted background. The units of the y-axis is in units of Counts per second per square centimeter per kilo electron-volt, while the x-axis will be in units of Energy (keV). This plot gives the user a vague idea on a general energy range to select for fitting (NOTE: This method is discussed in the FITTING section of the manual.). The user can also note from the plot where certain peaks occur in the background and data could be poorer. An example of such a peak is the proton-anti proton annihilation detection that creates a peak at the 511 keV enregy range (This peak should be noticeable on almost all background plots). To display a plot of the background, select the SPECTRAL FITS button from the ACTIONS row of the SPEX CONTROL PANEL. This action will cause the actions: spectral fits menu to appear. From this menu select the SPECTRAL PLOTS option. This will cause the spectral plots menu to be displayed. Next, from the spectral plots menu choose the BACKGROUND function. WSPEX will respond to this function by plotting the background in the SPECTRAL FITS window. The COUNTS plot in WSPEX displays the counts recorded by the detector along with the chosen background and model function. This type of display helps the user determine what is the exact range of energy in which the data is noticeably over the background. The energy range can be chosen right on the display (like previously described intervals) and sets WSPEX to only fit the model function within this range. This makes the COUNTS plot a valuable procedure to display for reliable data analysis. The counts plot is performed by first selecting the SPECTRAL FITS button from the ACTION row of the SPEX CONTROL PANEL. This action will display the actions: spectral fits menu. From this menu, choose the SPECTRAL PLOTS option, which will display the spectral plots menu. Finally, select the COUNTS function from the menu. WSPEX will then display the COUNTS plot. The spectral plot function: PHOTONS displays a plot of the photons per second per squared centimeter per keV versus the Energy (in keV). It is this display, also known as a spectral plot, that will be fitted against the different model functions. The x-axis, by default, also displays the values of the fit parameters for the current model function. This model function is also displayed, using the latest fit parameters, with the spectral plot. This display will help the user judge the closeness of the model function and will also help the user determine the range of correct values for the fit parameters. The first step in displaying a plot of the photons is for the user to select the SPECTRAL FITS widget button from the ACTIONS row of the SPEX CONTROL PANEL. Next, select the SPECTRAL PLOTS option from the actions: spectral fits menu. This option will cause the spectral plots menu to appear. From this menu select the PHOTONS function. WSPEX will respond by displaying a plot of the photons. NOTE: As stated earlier, the current printing of this manual does not include a description of the CALIBRATION CHECK function. ADJUSTING THE SPECTRAL PLOTS During the analysis of any of the above plots, it may become desirable for the user to adjust the plots displayed. There are a variety of reasons why adjusting the plots is advantageous for a user. Some reasons include: a given plot may include to much of the higher (or lower) energies, the scale of a particular axis may need changing, or a log axis may need adjusting to get closer to zero. Whatever the case, it is ultimately narrowed to two choices: either switching the scale or changing the range on the x or y axis. NOTE: Adjusting a spectral plot is different from adjusting the light curve, because both axis can be changed. To adjust the scale on either axis, select the SPECTRAL FITS button from the OPTIONS row of the SPEX CONTROL PANEL. Next, select either the XAXIS TYPE or YAXIS TYPE from the options: spectral fits menu, depending on the axis to be adjusted. Either choice selected will be followed by a menu displaying the two choices LOG or LINEAR. From this menu, select the setting the chosen axis is to have. The next spectral plot, and all other plots, will be plotted with the newly selected axis type. NOTE: The default of each SPECTRAL WINDOW plot performed by WSPEX will be log-log. The range of either axis can be switched by first selecting the SPECTRAL FITS button from the options row of the SPEX CONTROL PANEL. From the options: spectral fits menu, select either the YRANGE or XRANGE function. This action will display a MODIFY OPTION window with panels numbered 0 and 1 and labeled "SPECTRAL PLOTS YRANGE" (or XRANGE). Like the time history yrange modifier, the 0 panel is where the starting value should be entered and the 1 panel should hold the ending value for the axis (NOTE: IF the axis is LOG scale the starting and ending values should be an order of ten.). For these changes to take place on the current plot, the current plot must be replotted. BINNING Binning is the process of grouping an area of data points, averaging them together, and then plotting this average value over the area selected. WSPEX allows three methods for binning the spectral plots. The first two allows the user to select individual areas to be binned together as one group, while the last method allows an intervals' data to be binned in groups of a specific size (determined by the user). Binning doesn't effect the fitting of the model function to the data; however, it usually creates a clearer display of the plot for printout, which makes it a procedure worth performing at certain times. To start binning the data with any of the methods, select the SPECTRAL FITS button from the ACTIONS row of the SPEX CONTROL PANEL window. This selection will display the actions: special menu. From the menu select the SPEC. PLOT BINNING option. Next, choose the SELECT button. This action will cause a window, labeled "Interval Selection Mode" to be displayed. The window is the same window that appears when selecting other type of limit or boundaries. From the window select the GRAPHICAL INPUT button. This action informs WSPEX that selection of the intervals will be made on the spectral plot itself. Once the choice is made, another window labeled "Interval Selection" will appear. This window contains the three choices for the type of binning possible. The first two widget buttons, AS BOUNDARIES FOR CONTIGUOUS INTERVALS and AS BOUNDARIES FOR DISCRETE INTERVALS, are methods that are performed in the same manner except in the way the boundaries are handled. Both functions allow the user to select a group of intervals on the spectral plot and bin the data in the selected intervals together. To use either of these methods, select the proper button from the "Interval Selection" window. Next, start selecting the intervals, where data is to be binned together on the spectral plot, with the cursor (NOTE: The selection of intervals is performed in the same way as described in other procedure like selecting fit intervals or fitting energies.) Once all these intervals are selected, move the cursor out of the spectral plots window and select the DONE button from the newly displayed "Cursor Controls" window. This actions sets WSPEX to bin the given intervals, and the binning will be performed when the spectral plot is replotted. The third, and different, method of binning is selected by choosing the AS LIMITS ON SAMPLE GROUPS OF N (TO BE CHOSEN) widget button from the "Interval Selection Mode window". The selection of the button will cause the "Select A Number" window will appear. This window allows the user to select the group size of the data to be binned from the two columns of digits. After the grouping number is selected, close the window by pressing the window's READY button. Next the interval will need to be selected from the spectral plots window. After the interval is chosen, move the cursor outside of the SPECTRAL WINDOW box. WSPEX is now set to bin the interval into groups chosen soon as a the Spectral plot is replotted. DISPLAYING THE CURRENT OPTIONS Some of the options and settings dealing with spectral plots and fitting can be displayed within the INFO BOX. This information includes: the ranges of the fit parameters, the parameters "free" or "fixed", the function model chosen, and the range of the plot axes. The information displayed helps the user check the current settings before proceeding with a plot or fit that may waste time due to improper settings. This makes displaying the options an important action the user should learn. To display the options, select the SPECTRAL FITS button from the ACTION row of the SPEX CONTROL PANEL. Next, choose the SHOW CURRENT OPTIONS from the actions: spectral fits menu. The information will then be displayed in the INFO BOX. FITTING Data analysis is WSPEX's main function and the primary method of analyzing any flare is to compare the data with mathematical models. This process of comparison is known as fitting. Fitting informs the user how close the models actually represents what is occurring in the fare. In addition, the fit models also provide parameters (used in the fitting process), which provide values of certain flare characteristics. Examples of these characteristics include: the temperature of the thermal component, the emission measure and the area of interaction. These actual values for the flare model, called fit parameters, depend on the closeness of the fit and the fit model chosen. Each fit model has a varying amount of parameters, that may give different information about the flare. Therefore, it is important that the user becomes familiar with the fit models (and their parameters) offered and learns the steps necessary to produce a good fit. CHOOSING A FIT MODEL The choice of fit model is the first step in the fitting process. When WSPEX is first started, the default fit model is the thermal broken power law model (labeled fth_bpow). This model is designed to fit a function, using six parameters, with a thermal component at the lower energies and a broken power law towards the higher energies. However, the user may prefer a different fit model than the default model. If another fit model is desired, the user must select a new model to work with. The first action in choosing a new model is to select the SPECTRAL FITS widget button from the OPTIONS row of SPEX CONTROL PANEL. After the options: spectral fits menu is displayed, select the MODEL FUNCTION option. This action displays the model function menu, which will have a list of model functions to choose from along with a bottom function (OTHER) that allows the selection of a model not listed. From the menu select the desired model function. WSPEX will respond by using the selected model in any following spectral plots or fits. If the model function is not listed but does exist, follow all the procedures given above until the model function menu appears. From the menu select the OTHER function. This action will cause a "MODIFY OPTION" window to appear. The window has a single panel labeled "MODEL FITTING FUNCTION =>" Next, select the input area to the right of the panel label and enter the name of the model function. The final step is to select the DONE button; this will set WSPEX to use the new model function. SELECTING VALID ENERGIES It should be quite apparent to any user of WSPEX that any given fit interval will have good data, that is data above background, only within a certain range. It is only this range of energy the user should attempt to fit; otherwise, background will be fitted as well. This mistake will treat the background as good data and produce models, perhaps with good fits, that give inaccurate information. Therefore, it is essential for the user to learn the two method available for selecting an energy range. The first method of selecting an energy range is the graphical method. The method is similar to choosing intervals directly on the time history plot. The choice of intervals is selected directly on the COUNTS plot (NOTE: The interval selection can be made on the PHOTONS plot; however, the manual doesn't give a description of this method.). To select the graphic method, first activate the SPECTRAL FITS button from the ACTIONS row of the SPEX CONTROL PANEL. Next, select the FIT option from the actions: spectral fits menu. Once the FIT menu is displayed, select the SELECT ENERGY RANGE function (last function available). The action enables the user to select the energy range directly on the counts plot within the spectral window. After the minimum and maximum energy values are selected (and displayed on the plot as vertical lines), move the cursor out of the spectral window. This will make the "Cursor Controls" window appear. From the window select the DONE widget button. If the cursor is moved off the spectral window before both intervals are selected, choose the CONTINUE BY SELECTING FROM PLOT WINDOW action. The selection will allow the user can now finish select intervals from the plot window again. After the values are selected and the cursor controls window is removed, WSPEX is set to use the new energy range. The alternate selection method is to manually enter the values of the minimum and maximum allowed energy range. The procedure is performed by first selecting the SPECTRAL FITS button from the OPTIONS row of the SPEX CONTROL PANEL. Next, the VALID FITTING ENERGIES function from the options: spectral fits menu must be chosen. The function will display a MODIFY OPTION window, where the values are entered. The two panels, numbered 0 and 1, will hold the minimum and maximum values respectively. After the values are entered, select the DONE button on the window. WSPEX is now set for to use the energy range selected. NOTE: It is strongly encouraged that the graphical approach to selecting an energy range be used over the manual approach; it is a more reliable method than the manual approach. THE FIT PARAMETERS Every model function used in WSPEX has a group of fit parameters that represent certain aspects of the model. These parameters are values, given by the user or the WSPEX fit routine, that help determine how well the fit is between the model function and the data. During the course of trying to fit the function to the data, WSPEX changes the values of the "free" parameters so a better fit can be achieved. This is sometimes not desirable to the user, because the best fit could have unreasonable values for certain parameters. There is also the case when the value of a certain parameter is actually known to a certain degree of accuracy, being recorded by other sources that observed the flare. In this case, it would be advantageous for the user to set that parameter to the given value and "fix" the value so WSPEX can't change it while fitting. Therefore, the user must become familiar with the steps of viewing, changing, and fixing the fit parameters of a given model. NOTE: The parameters of the model functions available are not given in the current version of this manual. The first step in controlling the values of the fit parameters is learning how to view and change them. Both of these action are performed by first selecting the SPECTRAL FITS button from the OPTIONS row. Next, select the FIT PARAMETERS function from the options: spectral fits menu. The function will display a "Modify Option" window composed of a list of panels. Each panel contains the current value for an individual fit parameter. These panels can be viewed or a certain panel can be selected and the number held within the panel can be changed. Although each parameter can be changed, there is an upper and lower limit to the value that WSPEX will hold for each parameter. The values of the upper and lower limits are called RANGE_HI and RANGE_LOW. These values for RANGE_HI and RANGE_LOW can be found by displaying the current options of spectral fits in the INFO BOX (this method is given in the previous section). Once all the parameters are viewed and the desired changes are made, select the DONE button from the "Modify Option" window. The changes made to the parameters will be used on the next spectral fit. To "fix" a given parameter or "free" a previously fixed parameter, first select the SPECTRAL FITS button from the OPTIONS row of the SPEX CONTROL PANEL. Next, select the FREE/FIX function from the option: spectral fits menu. The function will clear the current menu and display an option toggle window. This window contains a list of the model function parameters (listed downward in the order in which they appear on x-axis) with a button to the left of each one. To free a particular parameter, select the button beside it until the button appears indented inward (PUSHED). To Fix a parameter, select the parameter's button until the button appears to be "popped" outward (POPPED). Once all the changes to the parameters are made, select the DONE widget button located above the list of parameters. The selected parameters are now "freed" or "fixed" accordingly and these changes will take effect on the next fit WSPEX performs. FITTING AND PLOTTING After a fit model is selected and the initial values for the parameters are set, the next step is to actually have WSPEX perform a fit to the data. The fit routine that WSPEX uses will try to find the best values for the free parameters given to produce the closest fit possible. The method used by WSPEX will also display the Chi-Square value, which will better inform the user on how close the fit actually is. This Chi-Square value, and the values for every parameter during every iteration of the fit routine, is displayed on the user terminal. After the fit calculations are performed, WSPEX can replot the existing spectral plot, displaying the new fit function in the process. Once the following step is performed, the user should observe the results and determine if the data needs refitting with different parameter values or if the current results are acceptable. To perform a fit after all fit parameters values are chosen, select the SPECTRAL FITS button from the ACTIONS row of the SPEX CONTROL PANEL. Next, select the FIT option from the actions: spectral fits menu. There are several options available from the FIT menu, The majority of all fit procedures performed by the user are done by selecting the FIT AND PLOT action. However, only a fit can be selected or a just the plot displayed by selecting the FIT or PLOT functions. After the FIT AND PLOT selection is made, WSPEX will perform the fit routine and replot the data with the new fit function, displaying the new parameters. The Chisquare value can be observed from the users terminal. The lower the Chisquare value the better the fit; however, there is a danger in getting the Chisquare value far below one. A good fit will have a range between 0.60 to 1.60, although there are exceptions and the range given should only be used as a very rough guideline. If the terminal is viewed while the fit routine is running, the user will notice that there is a set of Chisquare and parameter values given for every iteration of the routine. Although only the final set is the values WSPEX uses for the plot, the other iteration should be viewed. Viewing these iterations may provide the user with an idea on where to set parameters that need changing, so a better Chisquare can be achieved. SUMMARY FILES During the process of examining a flare, a user will certainly notice it takes a substantial amount of time to reach the process of selecting or fitting intervals. The majority of the time is taken by the steps to select the data, plot the light curve, subtracting the background and other events. These steps will have to be performed every time a new session is started with the same flare, which is a waste of time for the user. Fortunately, WSPEX allows the user to save all the information dealing with a flare into a summary file. This file is stored in the users personal directory and contains information about the data settings, the light curve itself, and the intervals selected for viewing in the spectral fits window. When the summary file is retrieved, it restores all this information, including a plot of the light curve, back into the WSPEX program. However, the summary file doesn't restore spectral plots or fits made at the time of the saving. These plots will have to be replotted and fitted again by the user. To save a summary file, first have an idea of all the process that need to be saved to avoid repeating when starting a new session. Next, do the steps necessary to activate these settings, intervals, etc. that are to be saved. Once WSPEX is set properly, select the SUMMARY button from the ACTIONS row of the SPEX CONTROL PANEL. From the actions: summary menu, select the WRITE SUMMARY FILE function. WSPEX will now save the current settings as a summary file in the user's directory. Restoring a summary file is an easy task to perform. It is better to restore a summary file from a new work session; otherwise, any work done before the restore action is activated will be lost. The first step is to select the SUMMARY button from the ACTIONS row of the SPEX CONTROL PANEL. The selection will cause the actions: summary menu to appear. From this window select the RESTORE SUMMARY FILE. WSPEX will then restore the summary file and bring the session up to the point where the file was saved, clearing the previous work in the process. POSTSCRIPT FILES (SENDING A PLOT) Another valuable feature offered by the WSPEX work environment is the ability to save and print any plot displayed by either the TIME HISTORY window or the SPECTRAL window. These files are saved as postscript files (filename.PS) in the directory the user selected before entering WSPEX. This allows the user to view the files outside of WSPEX with any viewer capable of handling postscript files. The files can also be printed, after being saved, with any printer capable of reproducing postscript files. These printouts provide the user with a hard copy of their results, that are sometimes better to see the data from than the actual display in WSPEX. NOTE: Any saving or printing done by the following actions will only save or print the last plot display by either of the graphical windows. Saving a file is the first step that must be done if the plot is to be viewed from a different program at a later time, or if the plot needs printed. There are two methods for saving a file. The first method is to select the SPECTRAL FITS button from the ACTIONS row of the SPEX CONTROL PANEL. The second method involves selecting the TIME HISTORY button from the ACTIONS row of the control panel. Both of the methods will produce menus with an option labeled "SEND LAST PLOT". This option should be selected, which will cause the send last plot menu to appear. Next, choose the TO FILE action. The plot is now saved as a postscript file. To print a file, follow the directions given above to first save a file. Next, follow the same steps for saving a postscript file until the SEND LAST PLOT menu is displayed. From this menu choose the TO PRINTER action. The file will now be printed to the present printer set in WSPEX. The x-axis and y-axis can be changed and chosen to display a variety of different parameter or labels in the space they are allotted. To change either axis, select the SUMMARY button from the OPTIONS row of the SPEX CONTROL PANEL. Next, choose the PARAMETERS TO PLOT option from the options: summary menu. This option will give another menu, allowing the user to choose either the x-axis or y-axis to change. From this menu select the appropriate axis to change. Once the selection is made, there will appear a set of parameters that can be plotted given the choice of axis. Then, choose the appropriate parameter for the desired plot. This process will have to be repeated for every parameter desired on the plot. After every parameter is chosen, the plot will contain the parameters on the given axis. NOTE: By default, the x axis starts with the fit parameters displayed; therefore, this parameter doesn't have to be selected. Both the saving and printing of a plot can be done together in WSPEX. First, follow the instruction for saving or printing a file until the send last plot menu appears. Next, select the TO FILE AND PRINTER action from the menu. The action will cause WSPEX to first save the plot as a postscript file and then print the newly created file. LEAVING WSPEX When finished working with WSPEX, the user can leave the program by activating the EXIT button within the SPEX CONTROL PANEL. This will remove the SPEX CONTROL PANEL and the INFO BOX; however, it will leave the other windows intact. To remove the TIME HISTORY WINDOW and SPECTRAL WINDOW, type EXIT at the IDL prompt on the user's terminal or console. This will exit the user from IDL, removing the graphical windows in the process. The user is now completely out of WSPEX.