pdm infile
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.
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.
debug
Flag to turn on debugging prints in the theta calculation subroutine.
cursor = stdgcur
The source of graphics cursor input.
Pdm applies a phase dispersion minimization algorithm 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,...).
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 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.
Print out the menu.
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.
i,k -- \fBgraph frequency or period respectively versus theta\fR
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 -- \fBgraph phase curve for period/frequency at cursor position\fR
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 -- \fBdelete/undelete respectively point nearest the cursor\fR
Points deleted will have an x drawn through them. The x will be erased when the point is undeleted.
f -- \fBcall ICFIT on displayed data\fR
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 -- \fBsubtract fit from data, use residuals\fR
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 -- \fBset sample range for calculations\fR
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.
g -- \fBsignificance of theta at cursor x position\fR
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 -- \fBamplitude and epoch at cursor x position\fR
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 -- \fBmark range and find minimum in this range\fR
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.
Redraw the plot on the screen.
x -- \fBremove a trend from the data by removing a bestfit line\fR
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 -- \fBflip the y-axis scale\fR
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.
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] \fBshow parameter settings\fR
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] \fBshow verbose information\fR
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 frequencyThese commands are self explanatory. Whichever value is set, period or frequency, the corresponding frequency or period is automatically calculated and remembered.
:ntheta [num] \fBset number of points for theta\fR
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] \fBset/show the sample ranges\fR
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] \fBfind theta significance\fR
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] \fBamplitude and epoch\fR
Same as the e key. Without an argument, use remembered minima.
:phase [period] \fBgraph phase curve\fR
Same as the h key. Without an argument, use remembered minima.
:unreject \fBunreject all points\fR
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 \fBreset range to entire dataset\fR
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 \fBreset data to original dataset\fR
Copy the original data vector into the working data vector.
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"
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 paraboli for the min and max points instead of actual data points.