THE SINGULAR-SPECTRUM-ANALYSIS TOOLKIT USER'S GUIDE

2. TOOLKIT DEMONSTRATION

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.

a. Basic Mouse Operations

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.

b. Getting Started

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.

c. Quitting

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.

d. Selecting a Time Series

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'.

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.

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.

e. FFT Spectrum

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.

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.

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.

f. Maximum-Entropy Method

If you pressed the `Maximum Entropy" button first, a new menu window opens and look like this:

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.

Once you have set these two controls, clicking the `OK' button will launch the MEM spectrum analysis. Immediately below the `MEM Order' slide, the word `Working...' will appear while the MEM calculations are made. In the window into which you originally typed `spectra' (to launch the Toolkit), various short messages reporting the status of the program will appear. For the most part (unless something goes wrong), these messages are of no concern. If something goes wrong, they will help to determine where in the program the problem occurred. Eventually, the message `Working...' in the Toolkit window will be replaced by the word `Done'. Soon afterward, a graphics window will open, looking something like this (if you didn't change the default resolution or MEM order):

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.


Next Section | Table of Contents | References
URL: users.guide.demo1.html
This file last modified: May
12, 1997