.help fplot Oct92 ftools.futils
.ih
NAME
fplot -- Plots columns from a FITS file using QDP/PLT Plot Package. 
.ih
USAGE
fplot infile[ext#] xdata[xerror] ydata[yerror]  rows device pltcmd 
.ih
DESCRIPTION
This task reads column data in from a FITS file and associates the 
columns with data vectors and optional error vectors which are then
passed along to a general purpose plotting package, QDP/PLT. It is 
recommended that the serious user of FPLOT become familiar with QDP/PLT 
by reading the NASA Technical Memorandum 4301, " The QDP/PLT User's
Guide" by Allyn F. Tennant, available at:

   http://heasarc.gsfc.nasa.gov/docs/software/ftools/others/qdp/qdp.html

The current implementation of FPLOT requires that the Host version of
FTOOLS be installed and that the user's account be properly configured
to use the Host version. See your system administrator or the "FTOOLS
Users Guide" by J. Kent Blackburn.
.ih
PARAMETERS
.ls infile [file name]
The file name and extension number of the extension to be copied.
.le
.ls xparm [string]
The name of the FITS column containing the x data along with the 
optional name of the FITS column containing the associated x error.
This combination is entered as one parameter of one of the following
forms: data[error], data{error}, or data.error. where data is the 
column name in the FITS file containing the x data and error is the 
column name in the FITS file containing the x error.  If this parameter
is blank or "-", the x axis values are taken to be the point number of
the y axis values.  This column may contain a vector, but must have
the same number of elements as the y axis values.
.le
.ls yparm [string]
The names of the FITS column containing the y data along with the 
optional name of the FITS column containing the associated y error.
Up to 8 parameters may be entered and the @filename convention may
by used. Note, Only 1 yparm (and optional error) may be given
for binmode = STACK (see below for more details). 
This combination is entered as one parameter of one of the following
forms: data[error], data{error}, or data.error. where data is the 
column name in the FITS file containing the first y data and error is 
the column name in the FITS file containing the y error.  The Y column
can be either a single value, a single element in a vector, or the
entire vector.  To specify a single element of a vector or array, use
the syntax ARRAY(100;4)[error].  If the entire vector is specified
(i.e. ARRAY[error]), the value plotted is either the entire vector or
the sum or the mean of all points based on the binmode parameter.
Note that on the Unix command line the characters ()[]; must be
preceeded by a \.
.le
.ls rows = "-" [string]
The range of rows to be output.  The default of - means print all rows.
The first ten rows could be specified as rows=1-10 or just rows=-10.
To print the first ten rows and all rows from 900 through the last
(inclusive), use rows=1-10,900-.  rows=1,3,7,23 will print only
those four rows. 
.le
.ls device = "/XT" [string]
The name of a supported QDP/PLT plot device. Typical installations will
support the following devices: /XTERM, /XWINDOW, /TEK4010, /GTERM, /PS,
/MAC, /NULL, /RETRO, /GF (Graph On), /VPS, /VT125, /OGTERM. Only the / 
followed by the first and second letters on the device name are required.
The default is for xterm devices.  A device may be overridden through the
pltcmd parameter by using the @filename convention (see below). If no device
is specified, the PGPLOT_TYPE environment variable is used. If PGPLOT_TYPE is
not set, the user will be prompted by PLT for a device type. Enter a "?" to
get a list of devices available.
.le
.ls pltcmd = " " [string]
This parameter represents any legitimate PLT command. A set of default
commands are generated to label the X and Y axes and provide a title based
on the contents of the FITS file. If more than one Y data column is to be
plotted the "PLOT Vertical" command is also generated by default, allowing
separate windows for each Y column. If more than three Y data columns are
to be plotted a "CSIZE .6" command is generated by default to reduce the
character size from the default size of 1.0. If the pltcmd is non-blank, it
will be appended to the default commands. If the pltcmd is quit/q or exit
then a "PLOT" command will be generated by default and placed before pltcmd
to cause a plot to be produced before exiting. The pltcmd can also be in the
form @filename, where the local file named filename.pco found in the current
directory contains one or more legal PLT commands. These commands can be used
to supplement or override the default commands.
The default commands are:
.le
.ls
	Device XTerm
.le
.ls
	LA X 'x column name' 'x column units'
.le
.ls
	LA Gn 'y column name' 'y column units' {n=2 for first y column}
.le
.ls
	CSIZE .6  {only if number of y columns > 3}
.le
.ls
	PLOT VERT  {only if number of y columns > 1}
.le
.ls
	LA T Plot of file 'file name'
.le
.ls
	LA OT Offset by 'value' {only if OFFSET is true}
.le
.ls
	PLOT {only if PLOTCMD is "QUIT/Q" or "EXIT"}
.le
.ls (offset = no) [boolean]
This parameter determines whether to use the first x axis value as an
offset for the x axis.  This is highly recommended for double precision
x axes, such as time, and in some cases (possibly when there are too few
points e.g. for NAXIS2 < 256) unless offset=yes, a bug in QDP appears to
be triggered, generating erroneous values for the x axis label.
.le
.ls (maxpts = 100000) [integer]
Maximum number of points per graph.  If additional points are requested,
additional graphs will be generated.
.le
.ls (binmode = 'DEFAULT') [string]
For vector Y columns, this parameter determines the value to be
plotted.  If equal to DEFAULT, each value of the vector is plotted,
and the X axis must also be a vector with the same number of elements
(unless no X axis was specified in which case the X axis gets filled with
the point numbers).  If SUM or MEAN is specified, the sum or mean of
all elements of the vector or array is plotted.  Vector columns can be
intermixed with single-valued, or indexed vector, columns only when binmode
is SUM or MEAN.  Otherwise all columns must be of equal size.  If STACK
is specified, each specified row of a vector column will be plotted in
a separate frame and stacked vertically, you may specify up to 8 rows.
.le
.ls (sensecase = yes) [boolean]
If true, column names will be searched for in a case-sensitive manner.
.le
.ih
EXAMPLES
.nf

1.  Plot the X and Y columns in the first extension of the FITS
    file test.fits using a PostScript device driver overriding the
    default Y axis label by specifying a PLT command to label
    the Y axis "Yvalue":

	ft> fplot test.fits[1] X Y - /PS "LA G2 Yvalue"

2.  Plot the first 500 rows of the X Y1 Y2 columns in the third extension 
    of the FITS file test.fits using an xterm device driver:

	ft> fplot test.fits[3] X "Y1 Y2" 1-500 /XT

3.  Plot the X Y columns in the first extension of the FITS
    file test.fits using an xterm device driver controlling the
    plot session with additional PLT commands in myplot.pco:

	ft> fplot test.fits[1] X Y - /XT @myplot

4.  Plot the TIME and VALUE columns in the 1st extension of the FITS
    file test.fits and place the output in a postscript file.  Avoid
    the final PLT> prompt so that FPLOT can be used in a script by
    setting PLTCMD to "quit":

	ft> fplot test.fits+1 TIME VALUE - /PS quit


5.  Plot TIME against the total of the values in the PHAS column
    where the PHAS is a vector:

	ft> fplot test.fits TIME PHAS - /XW binmode=sum

6.  Plot the (50,25) element of the 2 dimensional column ARRAY against
    row number:

	ft> fplot test.fits - ARRAY(50;25) - /xw

.fi
.ih
BUGS
Extra spaces between Y column names causes a non-fatal PLT error.
Some data (possibly with NAXIS2 < 256) trigger a known QDP/PLT bug 
which generates erroneous values for the x axis label; this can be
avoided by setting offset=yes.
.ih
NOTES
The maximum number of columns, be they data or error columns, is
currently 10.  The maximum number of Y axes is 8.  If more than 2000
points are being plotted, QDP/PLT ignores any error columns and just connects
the points specified by the data columns.
.ih
SEE ALSO
ftabcopy, fdump, fhisto, fcurve. fv, the interactive FITS file
editor, can also be used to plot table columns.
.endhelp
