pdm: Find periods in light curves by Phase Dispersion Minimization

Package: astutil

Usage

pdm infile

Parameters

infiles: Input file template. If more than one file matches the template, data from all the files will be concatenated to produce the working data set.

metafile = "pdmmeta": File in which to store metacode when running in batch mode. All of the plots saved will be put here with formfeeds between them.

batchfile = "pdmbatch": File in which to store information about the period, amplitude, epoch and fit function when running in batch mode.

device = "stdgraph": The output device for interactive graphics.

interactive = yes: Interactive flag. If set to no, the analysis is done in batch mode with output to a file and no interactive graphics. Metacode will be saved for the data plot, the theta plot, and the phase plot. If set to yes, various types of plots can be made on the user's terminal and cursor commands are available.

flip = no: Flag to tell the program to flip the y-axis. This is useful when the y-scale is in magnitudes (decreasing numbers mean increasing brightness).

minp = 0: Minimum period to be searched. This parameter, if set, tells the program the bottom end of the period window to be searched. If not set, the program uses as a value the smallest chronological distance between any two adjacent data points. When the program is run, it writes a value into this parameter as stored in the uparm directory. This means the next time the program is run, the default minp will be the value assigned or calculated the last time the program was run by this user. We say the program 'remembers' the last value used.

maxp = 0: Maximum period to be searched. This parameter, if set, tells the program the top end of the period window to be searched. If not set, the program uses as a value 4 times the distance between the first and last data point. This parameter is remembered as minp is.

ntheta = 200: Resolution of the theta plot. This parameter tells how many points in the period window should have their theta statistic calculated. The points are spaced equidistant from one another in frequency space.

pluspoint = 50: Maximum number of data points for which to use plus symbols. If there are more data points then points are plotted.

autoranges = no: This flag, when set, instructs the program to look for gaps in the data and, if large gaps are found, divide the data up into ranges discarding the gaps and doing the analysis only on the ranges. This helps remove side lobes from the spectra.

nsigma = 3: Number of standard deviations for autorange break. If ranges are to be automatically calculated, this parameter tells how large a gap in the data should constitute a division between ranges. The mean and standard deviation of the distribution of chronological spacing of input points are calculated. Then the points are scanned in increasing order and if an inter-data gap bigger than nsigma standard deviations is found, a new range is started.

cursor = "stdgcur": The source of graphics cursor input.

Description

Pdm applies a phase dispersion minimization algorithm (R. F. Stellingwerf, "Period Determination by Phase Dispersion Minimization", ApJ 224, 1978, 953) to lightcurve data to determine periodicities in the data. It also calculates amplitude and epoch information.

Pdm can be used in batch or interactive mode. In batch mode the output is period, amplitude, and epoch for the minimum found within the period window. Metacode will be produced for the data plot, the theta statistic plot, and the phasecurve plot. The metacode will be saved in the metafile. In interactive mode the user can plot the data at different stages in the analysis, fit and remove curves from the data, reject points, set data ranges, plot and fit phasecurves, etc.

Pdm guesses at the period/frequency window to be searched unless the minimum and maximum period for the window are specified using minp and maxp. The minimum period is taken as twice the chronological distance between the closest two points in the data. The maximum period is taken as 4 times the distance between the first and last data points.

Pdm will work on one object at a time and the input data may be contained in multiple input files if desired. The program will concatenate data in all the files which match the input template. The input files are text files containing one (x,y) pair per line or just a (y) value per line. If only one value per line is found the program will number x sequentially (1,2,3,4,...). If a third value is included on each line it will be read as the error in that measurement. (The 'e' key is used to toggle error bars on the phase plot.)

At startup, if the interactive flag is set, the user will be presented with a plot of the data and the cursor will be turned on.

When the user plots a phasecurve, points that are deleted or undeleted from the phasecurve plot will be deleted or undeleted from the working data set.

The ICFIT keystrokes are described elsewhere. (see help for icfit)

Phase Dispersion Minimization User Interface (keystrokes)

When the program starts up it reads the data file(s) and displays the data on the screen as a standard mark plot. The user is then placed in a graphics cursor loop with the following options available in addition to the standard graphics commands:

Note: The remembered period is for the last minimum found. This minimum calculation is done whenever a new theta plot is graphed and whenever the "m" key is used.

? -- list options: Print out the menu.

h -- graph data: Make a plot on the screen, using marks, of observation time vs observed value. If there are more than 50 points, use dots, else use pluses. If points have been deleted, draw an x through them on the plot. If ranges are in effect, draw range bars along the abscissa of the plot marking the ranges.

e -- toggle error bars on or off: When the phase plot is on the screen and error data has been supplied, this key will toggle the drawing of error bars on the phase plot so that the user can determine how well the period found works with the data including this error information.

i,k -- graph frequency or period respectively versus theta: Calculate the theta statistic in the period/frequency range specified previously. If no period/frequency range has been specified, pdm guesses one. The minimum period is taken as twice the chronological distance between the closest two points in the data. The maximum period is taken as 4 times the distance between the first and last data points. The number of theta points in this range is also a parameter which can be specified. Next, plot theta on the screen using line drawing mode. Plot either period vs theta or frequency vs theta. Calculate the minimum value of theta displayed, turn the cursor back on (clgcur) and put the cursor x position at that minimum.

p -- graph phase curve for period/frequency at cursor position: Calculate the phase curve for the period/frequency under the cursor. This assumes the user has a theta plot on the screen and an error message will be given otherwise. The phase curve will be plotted in mark mode with two copies displayed and placed end to end to clarify the plot by providing continuity at all phases. The amplitude and epoch values for this period are calculated and the phases are plotted relative to this epoch.

d,u -- delete/undelete respectively point nearest the cursor: Points deleted will have an x drawn through them. The x will be erased when the point is undeleted.

f -- call ICFIT on displayed data: ICFIT is used for interactive curve fitting. It is called with either the data values or the phase values, depending on which type of plot is on the screen at the time. Any point deleted in ICFIT will be removed from consideration in all subsequent calculations until restored. The fit curve is retained by PDM after the return from ICFIT and may be subsequently subtracted from the data using the j command. Note: The user must exit ICFIT using the q key before he is placed back into PDM.

j -- subtract fit from data, use residuals: Just as it says. The original data is retained and can be reinstated with the :origdata command. This command only applies to the data. The user cannot subtract a fit from the phase plot.

s -- set sample range for calculations: This command is used to set ranges of data to be used. The cursor is first positioned to the beginning of the range of interest, an s is struck, the program prints the prompt again:, the cursor is repositioned to the end of the range and a second s is struck completing the command. Multiple ranges may be set and all the data inside the union of the ranges will be used. Data points outside the ranges will be ignored until the data is reset with an :alldata or an :origdata command. This also forces the boolean flag segments to be set true.

,, -- Set minp or minf to cursor x position: When the theta plot is on the screen, this keystroke can be used to set the minimum period (frequency) to the current cursor position.

. -- Set maxp or maxf to cursor x position: When the theta plot is on the screen, this keystroke can be used to set the maximum period (frequency) to the current cursor position.

g -- significance of theta at cursor x position: The statistical significance of the period/frequency under the cursor is calculated by Fisher's method of randomization. This value is printed at the bottom of the screen. This assumes that a theta plot is on the screen.

a -- amplitude and epoch at cursor x position: For the period/frequency under the cursor or of the plot, the amplitude and epoch are calculated and returned to the user. This assumes that a theta plot is on the screen.

m -- mark range and find minimum in this range: This command is used exactly like the s command but has a different effect. After the user has positioned the cursor and struck the m key twice, defining the range, the minimum value of theta is found in this range and its associated period/frequency is returned.

r -- replot: Redraw the plot on the screen.

x -- remove a trend from the data by removing a bestfit line: This command calls the curfit package to fit a straight line to the data and then subtracts it point by point from the data.

z -- flip the y-axis scale: This command toggles a y-axis flip for the plots. This is useful when the user is plotting magnitudes where the smaller the ordinate value the larger the intensity.

q -- quit: Exit PDM.

The following commands may be abbreviated. If entered without an argument; :minp, :maxp, :minf, :maxf, and :ntheta will display the named parameter; :show, :vshow will print to STDOUT; :signif, :ampep, and :phase, will do the calculation at the remembered period.

:show [file] show parameter settings: Print on the screen the min/max period, the remembered minimum, the range if it is in effect, the start and end of the ranges if they are defined, the mean and variance of the data in each range. If file is specified, the output will go there.

:vshow [file] show verbose information: This command will display all the information displayed by the :show command plus curfit information if the any curves have been fit. Also, the residual data will be shown if residuals have been calculated. If file is specified, the output will go there.

:minp :maxp [period]            set min/max search period
:minf :maxf [frequency]         set min/max search frequency

: These commands are self explanatory. Whichever value is set, period or frequency, the corresponding frequency or period is automatically calculated and remembered.

:ntheta [num] set number of points for theta: Set the number of equally spaced points in the period window for which theta should be calculated. This is really a setting of the resolution of the theta plot and defaults to 200 since the calculation time for 200 points is only a few seconds. Very large numbers entered here will cause the program to warn the user that the theta calculation may take some time.

:sample [value] set/show the sample ranges: The start and end values for the ranges will be printed on the screen. If value is present, it has the form begin:end where begin and end are real numbers specifying a new range.

:signif [period] find theta significance: Same as the g key. The colon command allows the user to set the period exactly, instead of using the cursor. If no period is entered, the calculation will be done using the remembered period.

:ampep [period] amplitude and epoch: Same as the e key. Without an argument, use remembered minima.

:phase [period] graph phase curve: Same as the h key. Without an argument, use remembered minima.

:unreject unreject all points: This tells the program to use all of the data points. If a fit has been subtracted from a subset of the data points then this command causes the original data set to be restored since, otherwise, we would restore a mixture of data and residuals.

:alldata reset range to entire dataset: The effect of this command is to turn off the range settings. All of the data will be used if the ranges settings are off. Rejected points remain rejected though. Again, if these data are residuals, the original data are restored.

:origdata reset data to original dataset: Copy the original data vector into the working data vector.

Examples

1. To find the main period in the data contained in the file 'vstar645', whose period is within the bounds (200., 800.) interactively the command might be:

cl> pdm vstar645 minp=200. maxp=800.

2. To do the same thing in batch mode, allowing the program to guess the period window, with no lightcurve analysis, and saving the metacode in vstar645.m, the command might be:

cl> pdm vstar645 inter=no meta="vstar645.m"

Bugs

Pdm has some problems with data sets containing a small number (<20) points. Generally, it will do fairly well but the theta curve may look strange.

The amplitude and epoch calculation might be improved by fitting a parabola to the phase curve near the minimum and near the maximum and using points on these parabolas for the min and max points instead of actual data points.