Carlo manual

carlo - generate noise with statistics similar to input data.

SYNOPSIS

carlo input_file [-v] [-w|-ar] [-n realizations] [-seed seeds] [-wo components] [-ssa window] [-sig level] [-cov2|-cov3]

DESCRIPTION

Carlo will generate a user-specified number of zero-mean realizations of noise, each of which is the same length as the series in input_file and each of which contains the same variance and a memory that is selected by the user. The realizations can comprise white noise with the same variance as the data, noise that is reddened according to an autoregressive (AR) model that is fit to the data, or a partial SSA reconstruction of the data plus noise that is white or reddened but with characteristics fit to a reconstruction of all the remaining components. The reddened noise is constructed from an AR(1) model fitted to the input series or its partial SSA reconstruction. If the SSA reconstruction is selected, then the user also must specify the ssa window size and the list of components to be eliminated prior to fitting the AR model. The selected SSA reconstructions are removed, a noise model fitted, the selected number of time-series realizations synthesized, and finally the SSA reconstructions are added back in to each Monte Carlo series. Carlo writes a file that contains the Monte Carlo realizations, and also provides the option of using those realizations immediately to develop error bars for the eigenspectrum plots from ssa. If such error bars are desired, the user must specify the ssa window size and a significance level for eigenvalues to be output.

Upon successful completion, carlo produces the following output files:

mcarlo.out: contains the Monte Carlo realizations (of length equal to the time series in input_file).
mcsig.out: contains a list of ssa-component numbers and the corresponding eigenvalue at the (sig) and (100-sig) percent exceedence levels, where sig is the user-specified significance level.

input_file The file containing a scalar time series. The data is assumed to have a constant sampling rate, i.e., there are no gaps in the data record.

OPTIONS

-v: Selects verbose mode, which will send progress reports to the standard output [Default runs "silently"].
-w: Specifies that white-noise realizations be generated. This is the default.
-ar: Specifies that, instead, an autoregressive model with a single term be fit to the series in input_file and used to generate the Monte Carlo realizations. If both -w and -ar are specified, carlo stops with an error message. The AR model is always fit using the Burg algorithm.
-n realizations: Specifies the number of Monte Carlo realizations to be generated. [Defaults to 200.]
-seed seeds: Provides a list of seeds to the random number generator. Up to four integers can be specified in the form i1,i2,i3,i4. If any entries are left blank, that seed assumes the default value. Use verbose mode to see the default seed values.
-wo components: Compute realizations of noise plus an SSA reconstruction (RCs) of the data. components is a list specifying the RCs. The noisy part can be white or red, and has same statistics as the data minus the RCs. This option allows the user to test whether the data can be modelled as a "signal" plus "noise". If components is not provided, this option will default to -ar. SSA window size used in reconstruction is window as specified by -ssa.
-ssa window: Subject each realization to the first steps of SSA, and determine at which points the eigenvalues for SSA component number are outside of the two-tailed confidence interval specified by -sig. window specifies the SSA window size to be applied.
-sig level: Specifies the width of the confidence interval used with the -ssa option. level is an integer in the interval (0,100). For each SSA component, the 50 - level/2 and 50 + level/2 percentiles are written to mcsig.out. Specifying -sig without -ssa has no effect. [Defaults to 90]
-cov2: Specifies that the Vautard et al. (1992) algorithm be used to estimate the lag-covariance matrix used in the ssa operations initiated by either the -wo or -ssa options. Specifying -cov2 without -wo or -ssa has no effect. [Defaults to Burg (1978) algorithm.]
-cov3: Specifies that the Broomhead and King (1986) algorithm be used to estimate the lag-covariance matrix.

EXAMPLES

Given a time series in tseries.dat, generate 500 Monte Carlo series (of the same length as tseries.dat) of the default white noise with zero mean and standard deviation equal to that of tseries.dat:

  carlo -n 500 tseries.dat

Given a time series in tsery.dat, generate 200 Monte Carlo series (of the same length as tsery.dat) of zero-mean noise colored according to an AR(1) model fitted to the tsery.dat series, in verbose mode:

  carlo tsery.dat -v -ar

Given a time series in tseries.dat, generate 100 Monte Carlo realizations of AR(1)-colored noise with variance and memory similar to tseries.dat, and then calculate the 99 percent confidence bound on SSA eigenvalues from those noise series (using the Burg-algorithm approach to SSA and an SSA window size of 50):

  carlo tseries.dat -ar -ssa 50 -n 100 -sig 99

Given a time series in tsery.dat, generate 100 Monte Carlo realizations of white noise with the same variance as a reconstruction of tsery.dat MINUS the first two SSA components (from an SSA with the Vautard et al. (1992) algorithm for estimating covariance and with a window size of 70). Then use those realizations to determine the 95 percent confidence interval on SSA eigenvalues:

carlo tsery.dat -w -n 100 -wo 1 2 -ssa 70 -cov2 -sig 95

or, utilizing the defaults,

carlo tsery.dat -wo '1 2' -ssa 70 -cov2

REFERENCES

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

Broomhead, D.S., and King, G., 1986: Extracting qualitative dynamics from experimental data, Physica D, 20, 217-236.

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