WinWWZ Version 3, Release 2. - VB.NET

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

This software was developed by Geir Klingenberg, Lisa Henkel and Aaron Price
based on Quick Basic wavelet software developed by Grant Foster. 

The VB.Net code libraries used were funded by a Small Research Grant 
Gaposhkin Fund award by the American Astronomical Society.

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

--------------------------------------------------------------------------------


    ***************************************************************
    *** FOR ANY PAPERS WRITTEN USING RESULTS FROM THIS PROGRAM ***
        PLEASE CITE THE FOLLOWING PAPER:
  Foster, G. 1996, "Wavelets for Period Analysis of Unevenly Sampled Time
        Series," AJ, 112, 1709
     *************************************************************


 == QUICK START ==

 1. Unzip the package and run winwwz.exe
 2. Click "New Analysis"
 3. Load the file ztau.txt (included)
 4. Select the JD field & click "Set"
 5. Select the Mag field & click "Set and OK"
 6. Click "New Analysis Run"
 7. Stick with the defaults and click "OK"
 
 That's it! For details read further...

 == END QUICK START ==


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

 1. Unzip WinWWZ.zip
 2. Run winwwz.exe
 3. The program only works on Windows XP. You may have some luck installing it 
on Windows 98SE, ME, and 2000 by loading the VB.Net framework, 
    a library from Microsoft. Go here to download it:
    http://www.aavso.org/data/software/wwzwin.shtml

--------------------------------------------------------------------------------

3) Running the Program


Click "New Analysis" to load data. Highlight the time and magnitude 
fields when prompted. 

After the data is loaded click "New Analysis Run" to analyse the data. 
You'll be asked fro a variety of inputs, with 
recommended values already populated in the fields.

	- Low Time: Start time of data you want to be analyzed
        - High Time: End time of data you want to be analyzed
        - Time Step: Temporal resolution, steps between low time and high 
                     time to be analyzed
        - Low Frequency: Frequency to begin analysing at (f=1/d)
        - High frequency: Frequency to stop analysing at
        - Frequency Step: Frequency resolution, steps between low and high
                          frequencies to be analysed (delta f)
        - Constant: "Decay constant", this sets the "window" size of the 
                    wavelet.

The code will automatically select, based on your data, a generic 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.

When the analysis is complete you can save the data under the "File" menu so 
it can be loaded into your favorite plotting software.    

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 

	-min freq: 0.001
	-max freq: 0.020
	-delta f:  0.00001
        -decay:    0.001

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

The output data file is three-dimensional, with the wavelet Z-statistic
computed as a function of both time and frequency.  The data may be
visualized using any graphical plotting package, and we have included
scripts for both IDL and GNUPlot (the latter of which is available for free
for many operating systems).

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.

You can also save the "analysis" and all the settings and graphs by choose 
"Save Analysis" and then to use that analysis at a later date choose "Open 
Analysis".

--------------------------------------------------------------------------------

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

WinWWZ will give you four plots:

 - Contour Plot: A color 3 axis plot of time vs. freq. vs. power
 - Main Frequency: a 2 axis plot of freq. vs. time. It takes the 
   frequency with the highest power per window of time and plots it.
 - Main Period: a 2 axis plot of freq. vs. time. It takes the 
   frequency with the highest power per window of time and plots it.
 - Main Amplitude: a 2 axis plot of freq. vs. time. It takes the 
   frequency with the highest power per window of time and plots it.

You can also save the raw data under the File menu and load it into your 
favorite plotting software. See Section 3) above. 

--------------------------------------------------------------------------------

6) Reference & More Wavelet Analysis Information

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

Templeton, M. 2003, "Time-Series Analysis of Astronomical Data"," JAAVSO, 
         32, 41
         Paper is available in PPT and HTML at:
    http://www.aavso.org/aavso/meetings/spring03present/templeton.shtml
    ADS BIBCODE: 2004JAVSO..32...41T

Foster, G. 1996, "Wavelets for Period Analysis of Unevenly Sampled Time 
	Series," AJ, 112, 1709
    ADS BIBCODE: 1996AJ....112.1709F
    Scanned URL:
    http://adsbit.harvard.edu/cgi-bin/nph-iarticle_query?1996AJ....112.1709F



