TS version 1.2 (FORTRAN 77)

TS version 1.2

A time-series analysis program useful for the analysis of variable star and other ordered data.

The program TS, 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.

0) A note on functionality

The original version of this program was an interactive, graphics-based MS-DOS program written in the QuickBASIC computer language. The original program had more interactive features than the FORTRAN77 version, mainly because FORTRAN does not support graphics, and interactivity is limited to commands given within the program shell. Thus, the use of a graphical display program (such as gnuplot, mongo, or a spreadsheet) is recommended.

FORTRAN was used for this version both because of the current author's expertise, and because the language is commonly known and still in wide use by members of the scientific community.

We note that though some functionality is lost by porting the program com QuickBASIC to FORTRAN, there is a *vast* improvement in speed. Tests using the QuickBASIC and FORTRAN versions on the same computer show a factor of *20 or more increase* in speed using the FORTRAN version. The FORTRAN version is also capable of handling much larger data sets than the 8000 point limit of the QuickBASIC version.

Any individuals interested in volunteering to develop a graphical user interface (e.g. Java, VisualBasic) for this program are invited to contact the AAVSO at aavso@aavso.org.

1) Installation

The ts12.f and clean.f source codes are written in the FORTRAN77 computer language, and require 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 programs, at a shell prompt simply type

g77 ts12.f -o ts12 g77 clean.f -o clean g77 makesyn.f -o makesyn

The programs "ts12", "clean", and "makesyn" 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.

2) Launching TS1.2

Start the program by typing "ts12" at your shell prompt. You should see the following:

You may then enter the name of your data file. The data file must reside in the same directory that you launch the program from. The data should be in space-delimited columns, with time in the first column and the data value in the second. No explicit formatting is required.

After entering a valid filename, you will be asked to specify the start and end times of the data as a long integer. The units of time are arbitrary, though output periods and frequencies will be expressed in the same units as the input time values. The default time range is (JD) 0 to 2500000. You may press return to accept the defaults, or enter a long integer of your choice. If your data fully lie within your chosen range, the earliest and latest data points will define the range for all calculations.

After defining the range, the data will be loaded, and you will see the main menu:

Data file = tcas.dat start time = (JD 0000000) end time = (JD 2500000) 0: QUIT 1: Load data 2: Average data 3: Polynomial fit 4: Fourier analysis

At this point, you may select one of the menu options for analysis.

3) Data analysis: Averaging

If the data have significant scatter, or if you have large amounts of data (> 100,000 data points), you may wish to average the data prior to performing any analysis. For example, AAVSO visual data for long-period variables can be effectively averaged into 10-day bins without substantially altering the signals of interest.

To average data, select option (2) at the main menu, and when prompted, enter the size of the time bin, whether you wish to save the results to file, and the file name:

0: QUIT 1: Load data 2: Average data 3: Polynomial fit 4: Fourier analysis 2 Size of time slot = 10 Save these results to a file? (y/n) y File = tcas.ave 0: QUIT 1: Load data 2: Average data 3: Polynomial fit 4: Fourier analysis

When you enter the size of the time slot, the units must be the same as those of the data. You may enter this number as an integer, float, or exponential, but it will be read as a double-precision value.

If you wish to analyze the averaged data, you may either exit and restart the program and load the averaged data file, or you may choose option (1) "Load data" at the main menu prompt:

0: QUIT 1: Load data 2: Average data 3: Polynomial fit 4: Fourier analysis 1 Data file = tcas.ave start time = (JD 0000000) end time = (JD 2500000) 0: QUIT 1: Load data 2: Average data 3: Polynomial fit 4: Fourier analysis

4) Data analysis: Polynomial fitting

Subtraction of a straight line or low-order polynomial from your data prior to Fourier analysis is warranted in many cases, particularly in the analysis of stars whose mean magnitude varies during the time span of interest (e.g. dwarf novae during outburst).

To subtract a polynomial from the entire data set, select option (3) "Polynomial fit" from the main menu, and give the degree of the polynomial at the prompt:

0: QUIT 1: Load data 2: Average data 3: Polynomial fit 4: Fourier analysis 3 Polynomial degree: 1 POLYNOMIAL options: 0: EXIT POLYNOMIAL 1: Save constants 2: Save to file 3: Choose degree 4: Save residuals

The polynomial constants and residuals are automatically computed, and you are given a set of options as to what to do with them. If you wish to discard the polynomial fit, choose option (0) "Exit Polynomial". To save the computed polynomial constants, choose option (1) "Save constants", and to save the generated polynomial fit, choose option (2) "Save to file". In both cases, the results are saved to the (FILENAME).ts file. If you wish to recompute the fit with a different degree, choose option (3) "Choose degree" and enter the desired value as an integer. Finally, to save the residuals obtained by subtracting the fit from the data, choose option (4) "Save residuals", and give a valid filename. As with the "Average data" option in the previous section, you may reload the residuals with the "Load data" option on the main menu, or exit the program and load the residuals:

POLYNOMIAL options: 0: EXIT POLYNOMIAL 1: Save constants 2: Save to file 3: Choose degree 4: Save residuals 4 Residuals filename? tcas.res POLYNOMIAL options: 0: EXIT POLYNOMIAL 1: Save constants 2: Save to file 3: Choose degree 4: Save residuals 0 0: QUIT 1: Load data 2: Average data 3: Polynomial fit 4: Fourier analysis 1 Data file = tcas.res start time = (JD 0000000) end time = (JD 2500000) 0: QUIT 1: Load data 2: Average data 3: Polynomial fit 4: Fourier analysis

5) Data analysis: Fourier analysis

[Note: Section (5), with minor changes, was taken from the QuickBASIC documentation written by G. Foster. Information not relevant to the FORTRAN version of the program has been removed or modified. --M.T.]

To begin Fourier analysis, choose option (4) "Fourier analysis" from the main menu. Then TS takes you to the Fourier analysis menu.

(a) Choosing the frequencies (periods) to test

To determine whether or not the data are periodic, you must first decide which periods or frequencies you want to test. Several of the options, namely (1), (2), and (3), enable you to specify a range of periods or frequencies to test.

(i) option (1) Standard SCAN

The simplest choice is (1), the "standard scan." The smallest frequency (longest period) tested by the standard scan is 1/4T, where T is the total time span of the data. The standard scan will test frequencies from 1/4T to N/4T, where N is the number of data, in steps of 1/4T. [Note: Because TS utilizes a discrete form of the Fourier transform, the computation time will increase as the square of the number of data points. If you have 100,000 data points or more, consider averaging the data points prior to processing. -- M.T.]

As it tests each frequency, TS records the frequency, period, and power in your log file. Frequencies with the highest power levels are the most likely possibilities for the actual frequency of a periodic fluctuation in your data (if it has one; after all, not all data are periodic). Of course, you would like to know what these highest-power frequencies are, and the periods that go with them; that's why TS keeps a TABLE of the top-twenty frequencies/periods (see below how to access the table).

(ii) options (2), (3): frequency and period ranges

If you want to specify your own range of frequencies or periods to test, you can choose option (2) or (3) for the "frequency range" or "period range" options. First TS asks for the low frequency or period to test; enter the starting frequency or period. Then TS asks for the high frequency or period; enter the ending frequency or period to test. Finally TS asks for the "resolution." This is the spacing between test frequencies or periods. For instance, suppose you want to test a range of periods, from as low as 100 days to as high as 150 days. If you specify a resolution of 1, TS will test all periods from 100 to 150 in 1-day steps. TS is quite good at choosing the resolution itself. When TS asks you for the resolution of a frequency or period scan, if you enter 0, then TS will choose the resolution for you automatically.

(b) Modeling the data

(i) option (5) "delete from (or view) table"

Whenever the Fourier computation finds a frequency (period) whose power level is higher than its neighbors (i.e., when it finds a "peak"), TS checks the power level to determine whether or not this peak is one of the twenty best found so far. If so, it saves the relevant information (frequency, period, and power level) in its top-twenty table of the twenty best periods. Also, whenever you test a single period or frequency, its information is always stored in the table. The table only holds twenty entries, so if you put an entry in when the table is full, the bottom table entry will be "bumped off" -- and lost.

To view the table, select option (5) "delete from table". TS then displays the period and power level for the (as many as) twenty best peaks located so far. They are always listed in order, from the highest power level to the lowest. If you "bump off" an entry when the table is full, it is always the 20th (weakest) entry which is lost. After you select option (5) and the table is displayed, TS asks

Delete # (-1 to exit)

If you enter a number from 1 to 20, TS deletes the table entry corresponding to your number. This is a good way to make room in the table for new entries, or to "clear out the clutter" before beginning a new analysis. If you enter a number followed by the "+" sign, then TS deletes the specified entry and ALL OTHERS WHICH FOLLOW IT. Hence if you enter

Delete # (-1 to exit) 2+

Then TS will delete table entries 2 through 20, leaving only entry #1 in the table. If you enter -1, TS returns you to the Fourier analysis menu.

(ii) option (6) "model the data"

After determining the best periods, you may want to see exactly how they match the data. This is accomplished with option (6). After entering "6" at the Fourier options menu, TS displays the best-period table, and asks

Include frequency #1? Y

TS is asking which table entries you wish to use. It successively queries you about each frequency in the table. If you enter a "Y" (for "Yes") then TS includes that frequency in a multiperiodic fit to the data. If you enter "A" (for "All"), then TS will include the frequency being asked about AND ALL OTHERS WHICH FOLLOW IT. Thus if you respond

Include frequency #1? A

Then TS determines a multiperiodic fit using ALL the frequencies in the top-twenty table.

When you are done specifying the frequencies to be used in the fit, TS computes the best fit for those frequencies, and records to the log file the parameters defining it (the constant, and the cosine and sine coefficients for each frequency).

You might want to save these residuals. For this purpose TS finally asks

Save residuals to a file?

If you enter "y" (for "yes"), TS will ask you for a name for the file. It will then write to that file a single record for each data point, with 5 entries:

column 1. Time = Julian date.
column 2. Residual = difference between data value and the model function.
column 3. Observer ID (if you loaded observer IDs).
column 4. Original observed value.
column 5. Model function value.

This "residual" file is a powerful tool to look for more fluctuations in your data. You can load the data from this file (see the section on "loading data") and analyze it, too.

6) Fourier analysis: CLEANest analysis

TS is capable of refining one or more periods simultaneously. When you run a Fourier analysis of the data, it is possible that the "peak" signal or signals you detect may not be the precise frequency actually detected in the data set, because the sampled frequencies tested might be offset slightly from the true signals.

You can use CLEANest to refine one or more periods contained in the frequency table, and to add other test frequencies to the scan.

As an example, load the "tcas.dat" data set distributed with this code, and perform a standard scan. Look at the table of resulting frequencies:

Delete all but the first period by entering "2+" at the prompt. Now exit the table, and select option 8 -- "CLEANest spectrum". At the first prompt, type either "y" (for yes) or "a" (for all). You will then be prompted for two more responses: whether you wish to add more test frequencies to scan, and whether you already know a fixed period (such as a binary orbital period) to the scan.

At the prompt "enter number of variable periods: (0 for none)" you enter an integer containing the number of periods you wish to add to the scan. If none, enter "0". For any other integer, you will be prompted for that number of periods. The "variable periods" in this case means that TS will search about those periods, and find the strongest peak closest to what you selected. It does *not* mean that the period itself varies, but simply that the periods you enter are only approximate.

At the prompt "enter number of fixed period: (0 for none)" you enter an integer containing the number of fixed periods you assume while performing the scan. This option should only be used if you know that a period exists in the data, that you know it very precisely, and that it is stable. For example, if you know the period of a binary to very high precision but have not yet scanned for it in the initial scan, enter it here. If you do not wish to add a fixed period to the scan, enter "0".

CLEANest will then return to the Fourier menu. View the table. You should see that the first period (or the first several periods) have been displaced in the table, and that one or more periods should appear with higher strength above them. You should also note that the new periods all have the same power -- this is because the quoted power is the sum of the power of the individual components in the scan. If you wish to work more with these periods, delete the old test periods from the table, leaving only the newly refined ones.

FOURIER options: 0: EXIT FOURIER 1: standard scan (warning: may take awhile!) 2: frequency range 3: period range 4: fit polynomial 5: delete from table 6: model the data 7: SLICK spectrum 8: CLEANest spectrum 10: resolution magnification 8 1 435.7435 144.40 11 0.0000 0.00 2 0.0000 0.00 12 0.0000 0.00 3 0.0000 0.00 13 0.0000 0.00 4 0.0000 0.00 14 0.0000 0.00 5 0.0000 0.00 15 0.0000 0.00 6 0.0000 0.00 16 0.0000 0.00 7 0.0000 0.00 17 0.0000 0.00 8 0.0000 0.00 18 0.0000 0.00 9 0.0000 0.00 19 0.0000 0.00 10 0.0000 0.00 20 0.0000 0.00 Include period 1? a enter number of variable periods: (0 for none) 0 enter number of locked periods: (0 for none) 0 437. 0.00228832952 144.745762 438. 0.00228310502 144.711773 144.745762 0 438. 0.00228310502 144.711773 436. 0.00229357798 144.50794 144.745762 1 FOURIER options: 0: EXIT FOURIER 1: standard scan (warning: may take awhile!) 2: frequency range 3: period range 4: fit polynomial 5: delete from table 6: model the data 7: SLICK spectrum 8: CLEANest spectrum 10: resolution magnification 5 1 437.0000 144.75 11 0.0000 0.00 2 435.7435 144.40 12 0.0000 0.00 3 0.0000 0.00 13 0.0000 0.00 4 0.0000 0.00 14 0.0000 0.00 5 0.0000 0.00 15 0.0000 0.00 6 0.0000 0.00 16 0.0000 0.00 7 0.0000 0.00 17 0.0000 0.00 8 0.0000 0.00 18 0.0000 0.00 9 0.0000 0.00 19 0.0000 0.00 10 0.0000 0.00 20 0.0000 0.00 Delete # (-1 to exit) 2+ 1 437.0000 144.75 11 0.0000 0.00 2 0.0000 0.00 12 0.0000 0.00 3 0.0000 0.00 13 0.0000 0.00 4 0.0000 0.00 14 0.0000 0.00 5 0.0000 0.00 15 0.0000 0.00 6 0.0000 0.00 16 0.0000 0.00 7 0.0000 0.00 17 0.0000 0.00 8 0.0000 0.00 18 0.0000 0.00 9 0.0000 0.00 19 0.0000 0.00 10 0.0000 0.00 20 0.0000 0.00 Delete # (-1 to exit) -1

7) SLICK analysis

SLICK is a very useful tool for extracting multiple signal components from a given set of data. Unlike CLEANest which is essentially a peak-finding algorithm, SLICK iteratively searches for multiple frequencies in a given signal, and attempts to find a *best-fitting ensemble* of frequencies. There is a distinct difference between CLEANest and SLICK, in that SLICK will adjust each "found" frequency such that the overall signal strength is maximized. The two main uses for SLICK are in the extraction of multiple signals in data that is truly multiperiodic.

Since the procedure for SLICK is iterative, it is somewhat more time-consuming than normal analyses. The ideal procedure is as follows:

1) perform a standard scan
2) remove all but the strongest period from the table
3) run SLICK (option 7), and select a scan range (or use the defaults)
4) remove all but the strongest *two* periods from the table
5) repeat, increasing the number of periods left in the table each time, until there are no more significant signals remaining

At the end of this procedure, you should edit the period table to leave only the statistically significant signals, then run "model the data" (option 6). This will write the set of found periods to the log file, which may then be read by the program "clean" included with this distribution.

The multiple periods found with SLICK can be used for several different purposes, such as generating synthetic lightcurves, decomposing non-sinusoidal lightcurves into their Fourier harmonic components, or measuring period or amplitude variations. For more information on the latter, see G. Foster, "The CLEANest Fourier Spectrum", Astronomical Journal 109, 1889 (1995).

8) Exiting TS

From the main menu, enter "0". Note that all information not saved into the log file, or into a user-selected output file will be lost at this time.