SSA manual

ssa - perform Singular Spectrum Analysis on a time series

SYNOPSIS

ssa infile [-s nsig] [-w m] [-c1 -c2] [-t] [-sel clist] [-err2 -err3 cfac] [ -v ]

DESCRIPTION

ssa will perform singular spectrum analysis (SSA) on the time series in infile. ssa computes the eigenvalues and eigenvectors, or Temporal-empirical orthogonal functions (T-EOFS) for the given time series. The Toeplitz matrix of lagged covariances is computed via Burg's (1978) estimate. The algorithm also computes the Temporal Principal Components (T-PCs), derived from the T-EOF's projection onto the original time series. The error bars provided for the eigenvalues are based on the ad hoc estimate of Ghil and Mo (1991), although other estimates are available for comparison. Other user-specified options will perform pairing tests to identify oscillatory components, make a reconstructed time series from the leading T-PCs or user-specified components, and identify trends in the time series data.

Upon successful completion, the following output files are produced.
N.B. All output is written in e16.7 format.

test_ctr.out: contains the standardized time series, i.e., grand mean removed, and normalized by its standard deviation.
test_ev.out: contains the ssa eigenvalues. Column 1 is the eigenvalue index, column 2 the eigenvalue, columns 3 and 4 the low and high ad hoc error bounds, respectively, on each eigenvalue.
test_pct.out: contains the percentage of variance accounted for by each ssa eigenvalue. Column 1 contains the index, column 2 the percentage.
test_eofs.out: contains the user-specified number of leading T-EOFs, all normalized. Column 1 contains the index, columns 2 - nsig the T-EOF values.
test_pcs.out: contains the user-specified number of leading T-PCs. Format is the same as for test_eofs.out.
test_rc.out: contains the reconstructed (filtered) time series. Column 1 is the index, Column 2 the value.
test_pair.out: ** Not yet complete ** ; will contain information on the results of oscillatory pairs among the leading ssa components.

infile contains a scalar time series. The data should have a constant sampling rate, i.e., without gaps in the data record. The time series can be one column {x(t)} or two-column {t,x(t)} format.

OPTIONS

-s nsig: The number of "significant" components the user wants to keep in the analysis.
-w mg: The window size to be used in ssa. mg should not exceed 500, and for theoretical purposes, should not exceed 1/3 the number of points in the time series (Vautard et al., 1992)
-c1: Selects Criterion 1 in identifying oscillatory components among the user-specified number of "significant" components. The basis of this criterion is to determine which pairs of components among the potential clusters have nearly equal frequencies at which the reduced Fourier transform is maximum (cf. Vautard et al., 1992)
-c2: Selects Criterion 2 in identifying oscillatory components among the user-specified number of "significant" components. The basis of this criterion is to determine which pairs of components among the potential clusters have a high sum of reduced Fourier transforms (cf. Vautard et al., 1992).
-t: Selects trend test before reconstructing the ssa-filtered time series.
-sel clist: Selects which of the leading components from which to make the reconstructed time series. The components selected must be less than or equal to the number of significant components kept in the first pass of the analysis. The components to be used for reconstruction are specified in clistg, which is a list of component numbers, separated by commas.
-err2: Selects the ad hoc eigenvalue error bars described by Vautard and Ghil (1989).
-err3 cfac: Selects an intermediate formulation for the eigenvalues' error bars, based on the inverse of the lag-one AR coefficient. The user must input a real number cfac after this option, with a value between 1 and 2. Low values of this number will nudge the error bars towards the estimate of Vautard and Ghil (1989), while higher values of cfac will nudge the error bars in the direction of the Ghil and Mo (1991) estimate.
-v: Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].

EXAMPLES

Given a time series in tseries.dat, perform SSA with a window size of 150, keeping the leading 8 eigenvalues, T-EOFs and T-PCs:

ssa tseries.dat -s 8 -w 150

Given a time series in tseries.dat with 1200 points, perform SSA with a window size of 300, keeping the leading 10 eigenvalues, T-EOFs and T-PCs. Apply criterion 1 to identify oscillatory components, and produce a reconstructed (filtered) time series from the leading 10 components with trends removed:

ssa tseries.dat -s 10 -w 300 -c1 -t

Given a time series in tseries.dat, perform SSA with a window size of 60, keeping the leading 8 eigenvalues, T-EOFs and T-PCs. Apply criterion 2 to identify oscillatory components, and produce a reconstructed (filtered) time series from components 1, 2, 5 and 6:

ssa tseries.dat -s 8 -w 60 -c2 -sel '1 2 5 6'

REFERENCES

Burg, J. P., 1978: A new technique for time series data. Modern Spectrum Analysis, D. G. Childers (ed.), pp. 42-48, IEEE Press, N.Y.

Ghil, M., and K. Mo, 1991: Intraseasonal oscillations in the global atmosphere. Part I: Northern Hemisphere and tropics. J. Atmos. Sci., 48, 752-779.

Vautard, R., and M. Ghil, 1989: Singular spectrum analysis in nonlinear dynamics, with applications to paleoclimatic time series. Physica D, 35, 395-424.

Vautard, R., P. Yiou, and M. Ghil, 1992: Singular Spectrum Analysis: A toolkit for short, noisy, chaotic time series. Physica D, 58, 95-126