WWZ version 1.1

A time-series analysis program used to study the time-evolution of variable star data, capable of measuring changes in period, amplitude, and mean magnitude.

Program and documentation (c) copyright 2003 by the American Association of Variable Star Observers (AAVSO); all rights reserved.

The program WWZ, and its documentation, are the exclusive property of the American Association of Variable Star Observers (AAVSO). No part of the program, or the documentation, may be reproduced, distributed, copied, stored in an information retrieval system, or otherwise communicated, without the express written permission of the director of the AAVSO.

Contents

  1. Introduction
  2. Installation
  3. Running the Program
  4. Suggested Parameters
  5. Visualizing WWZ Output
  6. Reference

1) Introduction

The program WWZ computes the weighted wavelet Z-transform (WWZ) as defined in Foster (1996). The input data are a time series, i. e., a series of data x(n) together with the times t(n) at which they are observed. The data should be in an ASCII file, in columns separated by blank spaces. The maximum number of data points which can be loaded is 100,000.

The WWZ scans the data, at a selected range of times and a selected range of frequencies, recording the following statistics:

tau
The time being examined, in time units.
freq
The frequency being tested, in cycles per time unit.
WWZ
Value of the WWZ; this is approximately an F-statistic with N(eff) and 2 degrees of freedom, and expected value 1. It indicates whether or not there is a periodic fluctuation at the given time, of the given frequency.
WWA
Weighted wavelet amplitude; if the signal is periodic at the frequency being tested, this gives the (real semi-) amplitude of the corresponding best-fit sinusoid.
m(ave)
Mean apparent magnitude of the object at time tau
N(eff)
The effective number of data for the given time and frequency being tested.

These statistics are recorded to two files:

The FORMATTED OUTPUT FILE records all of the above statistics. It also contains a header summarizing the input data and the range of times and frequencies being tested.

The file "wwzper.dat" file records, for each time being tested, the frequency at which the WWZ is maximal. For this frequency, it records the corresponding period, amplitude, value of the WWZ, and N(eff).


2) Installation

The wwz11.f source code is written in the FORTRAN77 computer language, and requires a FORTRAN compiler. The codes have been successfully compiled using the GNU g77 compiler for linux and the GNU-based DJGPP compiler for MS-DOS. g77 is available as part of most freely-available linux or *NIX operating systems, and is typically distributed with the operating system. DJGPP is available for free from http://www.delorie.com

Other compilers have not been tested, and no support is available for those choosing to use other compilers. Optimization has not been tested and is not recommended unless you're confident in the optimizing functions of your compiler.

To compile the program, at a shell prompt simply type

	g77 wwz11.f -o wwz

The program "wwz" may then be moved to your binaries directory (such as /usr/local/bin on *nix systems). If errors occur, ensure that you have a working version of g77 on your system in a directory contained within your shell's path.


3) Running the Program

The data file you plan to use should lie within your current working directory. The data file is assumed to have two or more space-delineated columns, where the first and second columns contain the observation time and magnitude, respectively. [Note, the data should not contain data gaps larger than about 2 cycles.]

To run the program, type "wwz". You will be prompted for several inputs:

The code will automatically select the optimal time difference (delta tau) between wavelet scans, and scan the desired frequency range at each value of tau between the start and end of the data set.

Note that depending upon the length of the data set and the number of test frequencies, the output wwz file can be many megabytes in size. For a typical AAVSO mira star dataset, choosing

will result in a dataset between 5 and 20 megabytes in size.

Note also that if your scan will result in more than 1000 test frequencies, wwz will ask you to confirm this. Expect the program to run for between one and five minutes on a 500 MHz machine on an average AAVSO data set.


4) Suggested Parameters

The chosen frequency range should only gover the range of frequencies of astrophysical interest to reduce computation time. For Mira and Semiregular variables, choosing a frequency range between 0.0001 (P = 10000 days) and 0.02 (P = 50 days) with delta f of 0.00001 is reasonable, and should not oversample the frequency spectrum too severely. Be sure to choose frequency values that are physically relevant to the system you are studying, and to the data available.

The decay constant, c, defines the width of the wavelet "window". It defines the number of cycles of a given frequency f expected within the window. Smaller values of c will produce wider windows. Reasonable values of c are between 0.001 and 0.0125. Note that using small values of c will result in improved frequency resolution of variations, but will smear out temporal variations. Conversely, large values of c will improve the temporal resolution, but will generate larger uncertainties in peak frequency.

WWZ scans the data set starting from the earliest data and progressing to the latest. If you notice that the program returns zero values of the WWZ statistic, then you probably have a large data gap just prior to the point where the zero values begin. Consider truncating the data set to include only data before or after the gap, or split the data and analyze both sets separately.


5) Visualizing WWZ Output

The output data file is three-dimensional, with the wavelet Z-statistic computed as a function of both time and frequency. An IDL plotting script is included with this release. We would appreciate contributions of plotting scripts for other programs (MatLab, Excel, SuperMongo, GNUPlot); please contact AAVSO if you have written such a script and are willing to share it with others.

The wwzper.dat file is two dimensional, as it only contains the z-statistic of the strongest frequency at each tested time. This output may be plotted easily with a variety of plotting packages.


6) Reference

For a more detailed discussion of wavelets and the WWZ program, see the following:

Foster, G. 1996, "Wavelets for Period Analysis of Unevenly Sampled Time Series," AJ, 112, 1709