This section presents a demonstration of the major functions of the Toolkit. To follow along--once the SSA Toolkit has been installed (and added to your search PATH if necessary)--attach to the directory `demo' and proceed as described.
The Toolkit interface is based on a series of images of buttons and slides that will appear in small windows on your X-windows workstation. The Toolkit is operated by clicking and dragging various of these items. Only infrequently will you have to type in various names or numbers. These basic operations are accomplished through movements with your workstation's mouse and by typing on your keyboard, and are described below for those unfamiliar with the use of X-windows interfaces.
When you are asked to click on something, move the cursor to the object by moving your mouse, and then press down and release the left-most button on your mouse. To double-click, simply click twice in rapid succession.
When you are asked to drag something, move the cursor to the object by moving your mouse, then hold down the left-most button on the mouse while moving the mouse (and cursor and, presumably, the object) to where you want the object to be. Then release the mouse button.
When you need to type some name or number into a Toolkit window, move the cursor to the space where you want to make an entry (by moving your mouse). Then click within that space, type what you need, and proceed to the next step.
Finally, in the following, the notation `Hit <enter>' means press the button marked `Enter' or `Return' on your computer's keyboard.
Special Note---HANDLING ERRORS: Typically, when you enter a name wrong, or otherwise make a mistake in the Toolkit, the Toolkit will signal you in a special message that something is wrong or else may simply wait for you to try again. Occasionally, if you really manage to baffle the code, a tiny window may open with no room for a name or image, but still the Toolkit will wait patiently for you to try again. The window looks like the following on my workstation.
You may also get a blank spectrum or time series plot. Your best bet is to press on the `-' button on the extreme lefthand side of this tiny window (or the time series plot), drag down to `Quit', and thereby kill the little window or blank plot. Then try what you were doing again, correcting your mistake if possible. Less frequently, you may make a mistake that kills the Toolkit. In such cases, restart the Toolkit by typing `spectra' and try again.
Type `spectra' and hit <return> to launch the program `spectra', and the following dialog box will open.
Figure 1.--Initial
`spectra' window.
This menu offers push-button access to the basic functions of the toolkit:
We will work through examples using each in the sections that follow.
Notice that anytime you want to stop using the SSA Toolkit, you simply have to click on the `QUIT' button in the window above. The program will shut all of the associated windows and close all associated files.
Before applying any of the Toolkit tools, we must first read in a file containing the time series to be analyzed. (If you instead clicked on one of the Toolkit buttons before selecting a time series to analyze, then some error messages would appear in the window from which you started `spectra', but otherwise the Toolkit would simply wait for you to try again.) Two options for selecting the input file are:
Figure 2. `Select a File' window.
This new menu provides several Motif-like functions for browsing among your files, and then selecting the file that contains the time series you want to analyze. The functions and displays on the lefthand side of the window are:
Once you see the name of the file you want in this list, you can select it by double clicking on its name in this list.
The righthand side of the window has:
The Toolkit currently expects the input series to be in the form of:
For this tour, let's start with the noisy time series called `soi' that is stored in a file of the same name in the "examples' directory as an ASCII list of 512 x(t) values, one per line. To choose the time series `soi' for analysis, either:
The `Select a file' window closes (if there has been no problem), and the Toolkit window looks like:
Figure 3. Spectra
window, after an input file is selected.
with the name of the input series appearing in the slot below `Input file'.
Special Note---SIMULTANEOUS TOOLKIT APPLICATIONS: The user may be tempted to apply the Toolkit to several time series simultaneously. However, the Toolkit only can be applied to series sequentially. That is, at any given time, Toolkit procedures always are applied only to the time series named in the `Input File' slot. Furthermore, launching more than one `spectra' window at a time will yield unpredictable results.
After a moment, a time-series plot of the data will appear in a graphics window. The series is plotted with series values on the y axis and time on the x axis. Time is plotted from 1 to N, where N is the number of data points in the series.
Figure 4. Input series plot (soi), when IDL graphics package is specified.X-axis
units are months, and y-axis is dimensionless SOI units.
The time series `soi' that we have read in is noisy, with no deterministic periodicities apparent amidst the background signal. In fact, `soi' is a list of monthly values of the Southern Oscillation Index (SOI), a climatic index connected with the seasonally recurring, oceanic El Niño condition (Bjerknes, 1969; Rasmusson et al., 1990; Keppenne and Ghil, 1992). The series `soi' was derived from monthly mean sea-level pressures at Tahiti and Darwin, Australia, by removing their annual cycles, dividing the resulting anomalies by the corresponding standard deviations, and then taking the Darwin-minus-Tahiti difference (cf. Keppenne and Ghil, 1992). The SOI series considered here is for the time interval from January 1942 through December 1990, during which no observations are missing.
Special Note---CHOICE OF GRAPHICS PACKAGES: The time-series plot above was generated by the Toolkit's "hook" to IDL, a proprietary plotting program. The Toolkit can produce these displays using any of several graphics packages depending on which one you have loaded on your system. Currently the choices are:
To tell the Toolkit which package to use, create a file called `.spectra' in your home directory (or the directory where you activated the Toolkit) containing one of the following commands:
set viz IDL
set viz XGRAPH
set viz GNUPLOT or
set viz NULL.
Restart `spectra' if necessary by clicking on the `Quit' button, editing the .spectra file, and then typing in `spectra <enter>' again.
Special Note---PRINTING TOOLKIT SPECTRA AND TIME SERIES: The procedures for printing out a copy of any of the spectra generated by the Toolkit depend on which of the graphics packages is used. In order to print a graph from the particular graphics package you are using, you will have to familiarize yourself with that package. For example, a file called `README.xgraph.users' is provided in the `doc' directory to get xgraph users started.
Once the time series is displayed, you are ready to apply the various tools to it, in whatever order you choose.
Progress messages (including some error messages), MTM results, and the results of various SSA tests for oscillations and trends are viewed by clicking the "Show Log" button at middle right of the Toolkit menu. An editor window opens with all the various messages that the Toolkit generates. While this editor window is open, the rest of the Toolkit is frozen and will not function. If the editor is emacs, you can close the window by typing ctrl-X ctrl-C somewhere in it.
Special Note---CHOICE OF EDITORS: The editor that is used to display the log can be specified by adding another command to the `.spectra' file in your home directory (or where you activated the Toolkit from). To specify that the log be shown in the emacs editor, include the command
set EDITOR emacs
to specify that `xedit' be used
set EDITOR xedit
and to specify that the vi editor be used
set EDITOR "xterm -exec vi"
in the .spectra file. The first two options above show how any separately window-ed editor can be used. Editors that use the current window must be accessed according to the third option.
If you clicked the `FFT Spectrum' button first, a new menu window opens and look like this:
Figure 5.
Fourier Transform menu.
The `Fourier Transform' extension to the original menu controls the application of Blackman and Tukey's (1958) window-correlogram procedure for estimating time-series power spectra. There are two slide controls below the `Fourier Transform' title.
Alternatively, you can type a resolution into the slot on the far right of the slide to specify an exact number. The Toolkit does not expect you to hit <enter>; instead as you change the number shown, the slide will move automatically to reflect your entry.
Below the slides are a series of `Window type' buttons which are clicked to choose the shape of the windowing function to be applied in estimating the correlogram. These buttons are activated by clicking on one. At any time, only one can be chosen. The window shapes available are:
As Press et al. (1989) have noted, the choice of window functions is usually not as important as the choice of window size.
Once you have set these two controls, clicking the `OK' button will launch the correlogram analysis. Very soon, a graphics window will open, looking something like this (if you have set the resolution to 512 and window size to 77):
Figure 6.
Correlogram plot for `soi'. X-axis units are cycles per month; y axis is
power density.
The plot shown here looks different from the previous time-series plot because (1) it is instead a power spectrum, plotted with the log of power spectral density on the y axis and frequency on the x-axis; and (2) more basically, this one is plotted with xgraph instead of IDL. To learn about the options available within this graphics window, find and read the file called `README.xgraph.users' in the `doc' directory.
Special Note---AUTOLAUNCHING: If the Toolkit did not wait for you to press the `OK' button before performing the calculation, and if you want it to wait, then make sure that the autolaunch is set properly in the .spectra file mentioned above (in the context of choosing editors and graphics packages). The command
set AUTOLAUNCH {fft}
in .spectra will tell the Toolkit to perform an initial FT analysis with the default values immediately upon opening the `Fourier Transform' part of the Toolkit menu. To turn this option off, just make sure the list in brackets after set AUTOLAUNCH does NOT contain the word `fft'. To autolaunch the other applications, include the words mem, mtm, and ssa in the list.
The frequencies in the power-spectrum plot generated by the Fourier Transform program (as well as MTM and MEM) are expressed in terms of fractions of 1/D. The range plotted is from 0 cycles to 1/2 cycle per sample period. The latter is the Nyquist frequency, 1/2D, and is the theoretical upper bound on frequency information in a discrete time series (see Press et al., 1989, section 12.1).
The power spectrum displayed in the graphics window above shows peak power between frequencies of zero and about 0.05 cycles per month. There is an indication that this plateau may contain two peaks, one at about 0.019/month and the other at 0.037/month. These correspond to periodicities of about 52 months and 27 months respectively. To the extent that we believe that these are two non-spurious spectral peaks, we may tentatively guess that they correspond to the quasi-quadrennial (QQ) and quasi-biennial (QB) components of El Niño (Rasmusson et al., 1990), respectively.
These peak frequencies can be pinpointed by saving and looking at the spectrum values (below) or, when using some graphics packages, by various operations within the graphics window. For example, in the xgraph plot above, x-y coordinates listed at lower right indicate the cursor location in the plot units (x=frequency, y=power). Thus, by putting the cursor on a peak, its frequency and power can be read directly from the screen.
Until the correlogram analysis has been performed at least once, the label on the `Save' button on the right is faint whereas the label on the `Save As' button is bold. Clicking the `Save As' button will activate a file-selection window that is essentially the same as the one used to open `soi' in the first place. Decide on a file name to which you want the correlogram spectrum values saved. Subsequently (after you have selected a name at least once), clicking the `Save' button will save the spectrum to the most recently chosen file name. Clicking `Save As' will give you the option of choosing another file name. In either case, the Toolkit saves an ASCII list of frequencies, power densities, and error bars to the selected file. Clicking the `Help' button in the far lower-right corner of the Toolkit menu opens a small window that tells what the various FT buttons do.
To help show some of the strengths of the various tools, let us also quickly analyze another time series. Type the file name `ssa_mstr' into the `Input File' slot at the top of the main Toolkit menu, and a plot will appear of an artificial time series consisting of two oscillations with nearly equal frequencies plus some white noise. The two oscillations "beat" against each other with a result that alternates between large and small amplitudes as the two move in and out of phase between cancellation and reinforcement.
Once the new series is read and its time-series plot appears, you can immediately perform a correlogram analysis by clicking on the `OK' button in the `Fourier Transform' part of the menu. The result looks like the following (when a resolution of 512 and window size of 77 is selected) (figure 7).
Figure 7. Correlogram for `ssa_mstr'.X-axis units are cycles per sample,
and y-axis is power density.
Notice that the correlogram distinguishes only one peak in this signal. We will want to compare this response to the results from MTM and MEM analyses.
Figure 8. Maximum Entropy Method menu.
There are two slide controls below the `Maximum Entropy Method' title, and the file name for the data you are analyzing.
Alternatively, you can type a resolution into the slot on the far right of the slide to specify an exact number. As you type in the number, the slide will move to take that value automatically so that you need not hit <enter> after typing in a resolution.
As above, you can also type the desired MEM Order into the slot on the far right.
Figure 9. MEM spectrum for `soi'. X-axis units are cycles per
month, and y-axis is power density.
The MEM spectrum for the SOI appears to corroborate the correlogram analysis earlier by including strong peaks with periods around 52 (QQ) and 26 (QB) months, which are accompanied by a large number of smaller peaks at higher frequencies. Many of these other peaks may be spurious.
Applying MEM to the artificial series `ssa_mstr' yields the following spectrum (figure 10).
Figure 10. MEM spectrum for `ssa_mstr'. X-axis units are cycles
per sample, and y axis is power density.
Notice that MEM analysis IS able to distinguish the two distinct harmonics that were built into the series. The peaks appear at frequencies 0.225 and 0.220 cycles/time step, respectively. This greater resolution of harmonics is surely the most attractive feature of MEM.
The `Save', `Save As', and `Help' buttons on the right side of the MEM part of the Toolkit menu function in the same way as the corresponding buttons in the Fourier Transform section.