fplot HEADAS help file

NAME

fplot -- Plots columns from a FITS file using QDP/PLT Plot Package.

USAGE

        fplot infile[ext#] xdata[xerror] ydata[yerror]  rows device pltcmd

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.

PARAMETERS

infile [file name]

The file name and extension number of the extension to be copied.

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.

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 \.

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.

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.

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:

: Device XTerm
: LA X 'x column name' 'x column units'
: LA Gn 'y column name' 'y column units' {n=2 for first y column}
: CSIZE .6 {only if number of y columns > 3}
: PLOT VERT {only if number of y columns > 1}
: LA T Plot of file 'file name'
: LA OT Offset by 'value' {only if OFFSET is true}
: PLOT {only if PLOTCMD is "QUIT/Q" or "EXIT"}

(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.

(maxpts = 100000) [integer]

Maximum number of points per graph. If additional points are requested, additional graphs will be generated.

(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.

(sensecase = yes) [boolean]

If true, column names will be searched for in a case-sensitive manner.

EXAMPLES

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

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.

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.