Initial commit

1 files changed, 372 insertions, 0 deletions

diff --git a/noao/astutil/doc/pdm.hlp b/noao/astutil/doc/pdm.hlp
new file mode 100644
index 00000000..51b24d5f
--- /dev/null
+++ b/noao/astutil/doc/pdm.hlp
@@ -0,0 +1,372 @@
+.help pdm May87 noao.astutil
+.ih
+NAME
+pdm -- Find periods in lightcurve data.
+.ih
+USAGE
+pdm infile
+.ih
+PARAMETERS
+
+.ls 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.
+.le
+.ls 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.
+.le
+.ls batchfile = "pdmbatch"
+File in which to store information about the period, amplitude, epoch
+and fit function when running in batch mode.
+.le
+.ls device = "stdgraph"
+The output device for interactive graphics.
+.le
+.ls 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.
+.le
+.ls 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).
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls pluspoint = 50
+Maximum number of data points for which to use plus symbols.  If there
+are more data points then points are plotted.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls cursor = "stdgcur"
+The source of graphics cursor input.
+.le
+.ih
+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.
+
+.ls ? -- list options
+
+Print out the menu.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls ,, -- 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.
+.le
+.ls . -- 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.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls r -- replot
+
+Redraw the plot on the screen.
+.le
+.ls 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.
+.le
+.ls 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.
+.le
+.ls q -- quit
+
+Exit PDM.
+
+.le
+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.
+
+.ls :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.
+.le
+.ls :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.
+.le
+.nf
+
+:minp :maxp [period]		set min/max search period
+:minf :maxf [frequency]		set min/max search frequency
+.fi
+.ls
+These commands are self explanatory.  Whichever value is set,
+period or frequency, the corresponding frequency or period is
+automatically calculated and remembered.
+.le
+.ls :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.
+.le
+.ls :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.
+.le
+.ls :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.
+.le
+.ls :ampep [period]		amplitude and epoch
+
+Same as the e key.  Without an argument, use remembered minima.
+.le
+.ls :phase [period]		graph phase curve
+
+Same as the h key.  Without an argument, use remembered minima.
+.le
+.ls :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.
+.le
+.ls :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.
+.le
+.ls :origdata			reset data to original dataset
+
+Copy the original data vector into the working data vector.
+.le
+.ih
+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"
+
+.ih
+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.
+
+.ih
+SEE ALSO
+icfit
+.endhelp