Time Series Tool: Period Finder

Contents of page/chapter:
+Initial View
+Settings and Adjusting Periods
+Plot
+Calculate Periodogram
+Periodogram Results
+Accepting a Period

Initial View

When you click on the "Period Finder" button, this is the screen you get:

The upper left is another pane, and the upper right will have (eventually) a plot of the light curve. Initially, there is nothing here because no period has been determined yet.

Now we describe these portions of the screen, as well as what to do next.

Settings and Adjusting Periods

The settings pane carries with it the time and dependent variable columns you set in the Viewer (prior screen). These columns cannot be changed from here; you must return to the main screen to change them.

You can set the period from this screen in three different ways:

Enter manually. Just type the period you want in the box.
Slide to select. The boxes on the far left and right of the slider control the range over which the slider applies. By default, it comes up with 0.001 d and 365 d. If your target has, say, a period near 0.7 d, but you are not sure exactly what it is (perhaps due to changes in the source itself), you can reset the slider limits to be 0.5 and 1 d, then click and drag the slider slowly through the various periods. The plot of the phased light curve in the upper right changes dynamically as you move the slider.
Calculate periodogram and click to select period. To use this option, click on the "Calculate periodogram" button either here or in the lower portion of the screen (see below for more information).

It has also extracted the time of the first epoch in your data file and listed it in the box labeled "Time Offset." You can change this if you want.

Once you have a period you like, click "accept" to accept means to return to the main screen, and plot the phase folded light curve using the selected period on that screen. Cancel to return to the main screen without phase folding the light curve.

Plot

The plot in the upper right is a plot of the uploaded light curve, phased to the currently selected period. It comes up without an initial period. If you enter a different period in the settings pane, then this plot dynamically updates.

⚠ Tips and Troubleshooting : This plot is unlike any other plot within this tool in that you cannot control what is plotted or how. Because this tool was built to work primarily with ZTF/PTF and WISE/NEOWISE data, both of which are in magnitudes, at least for now, it's going to plot small numbers at the top of the y-axis in this screen. Apologies to everyone working in flux or temperature or anything else where big numbers should be at the top.

Calculate Periodogram

When you first load this portion of the tool, the bottom has only a "Calculate Periodogram" button. Clicking on it starts the process of the periodogram calculation. The code that is actually run by the tool is that from NExScI periodogram service

Clicking on the button brings up this configuration pop-up:

From here, you can select from drop-down menus:

Periodogram type. Lomb-Scargle is the only choice. (Lomb-Scargle is an approximation of the Fourier transform for unevenly spaced time sampling. It identifies periodic signals that are simple combinations of sinsinusoids.)
Period step method. You can select fixed frequency or fixed period.

The next set of choices are left blank by default: Fixed step size, period min, and period max. If you leave these variables blank, the routine will calculate values for these parameters as follows:

fixed step size - if using fixed frequency, this is the delta f; if using fixed period, this is the delta P. The default value is (max-min)/(number of periods to sample), where number of periods to sample is 10 times the number of data points.
period min - minimum period to calculate. The default value is twice the median time step in the data (which is about the Nyquist limit).
period max - maximum period to calculate. The default value is half the time baseline.
number of peaks - number of peaks to identify in a separate table returned by the calculation. The default is 50.

If you want to override any of these selections, you can do so in the boxes in the pop-up.

Click on 'Reset' to reset the parameters to the defaults.

Click on 'Cancel' to close the pop-up without doing anything.

Click on 'Calculate' to initiate the calculation.

After a periodogram calculation has been completed, a "Recalculate Periodogram" button is located in the settings pane.

Periodogram Results

The results of the periodogram calculation appear in two tables (left) and a plot (right), both on the bottom of the screen.

On the left, the two tables are (1) the periodogram itself (which is in the foreground by default) and (2) a table listing just the top N peaks, where N is a value you specify in the periodogram finding pop-up (the default is 50).

On the right, the periodogram is plotted. This is a plot with all the same basic functionality provided by this tool in that you can change what and how it is plotted -- for example, if you want to remove the lines connecting the points, click on the gears () to bring up options for the table and choose a different plot option from the pop-up.

The plots and tables are dynamically linked. If you click a point in the periodogram, the row is highlighted in the table, and the phased light curve changes. In the settings pane, the period next to "enter manually" is updated to reflect the period you selected.

If you select the other table, the table of peaks, on the left, all the same functionalities apply, except the plot on the lower right is now power versus peak number.

(This power spectrum and period are what you get if you use this example input table from NEOWISE.)

⚠ Troubleshooting 1: power spectrum does not have a single peak
If your light curve is sampled with large gaps (as a lot of WISE/NEOWISE and ZTF/PTF light curves are), use caution when interpreting the power spectrum. For example, here is the NEOWISE light curve for VY Lib, a variable star. If you plot that light curve, you will see big gaps between clumps of observations.

	This is what you get if you let the period searching routine pick all its own defaults. The period is 0.5339 d. There is a peak at that period that sticks up above the noise.
	This is what you get if you force the minimum period to be 0.1 d, which changes the influence of the gaps. The 0.5339 peak no longer stands out from the other peaks, and with just this result, one could justifiably conclude there is no significant period here. Except there really is one, and it's 0.5339 d.
	This is what you get if you use only three of the campaigns (three of the groups of points). There are fewer points overall, but there are also fewer big gaps in the light curve. Now the distribution of peaks in the power spectrum has changed again. Caution is warranted when interpreting power spectra, especially if the time series has large gaps. Simulations are helpful to know what to believe.

⚠ Troubleshooting 2: The version of Plot.ly used by IRSA Viewer sometimes makes ...unusal label choices for logarithmic plots. The two minor ticks between major ticks are 2 and 5, so if they occur between 10 and 100, it means 20 and 50.

Accepting a Period

In practice, you may want to work with all of the available tools to find a period -- periodograms calculated in different ways, different peaks selected, sliders used to align particularly ill-behaved waveforms, etc. After you have a period that you like, put that value in the box next to the "enter manually" text in the settings pane.

The buttons in the lower left of that pane now read "accept" and "cancel." 'Cancel' closes the period-finding window without doing anything further. 'Accept' takes that period as the best possible period, and returns you to the main screen, but now that screen is a little different, because it is after Period Finding.

Go back to Main Screen, Viewer (Initial View) or go on to Main Screen, Viewer (After Period Finder).