All Packages Class Hierarchy This Package Previous Next Index
Class ptolemy.plot.Plot
java.lang.Object
|
+----java.awt.Component
|
+----java.awt.Container
|
+----java.awt.Panel
|
+----ptolemy.plot.PlotBox
|
+----ptolemy.plot.Plot
- public class Plot
- extends PlotBox
A flexible signal plotter. The plot can be configured and data can
be provided either through a file with commands or through direct
invocation of the public methods of the class. To read a file or a
URL, use the read() method.
When calling the public methods, in most cases the changes will not
be visible until paint() has been called. To request that this
be done, call repaint(). One exception is addPoint(), which
makes the new point visible immediately if the plot is visible on
the screen.
For backwards compatibility with an older program, pxgraph, the
readPxgraph() method reads pxgraph-compatible
binary files. Since those binary
files have no format information, and format information in pxgraph is
provided by command line arguments, a method parsePxgraphargs() is
provided to interpret the pxgraph-style command-line arguments.
The ASCII format for the file
file contains any number commands,
one per line. Unrecognized commands and commands with syntax
errors are ignored. Comments are denoted by a line starting with a
pound sign "#". The recognized commands include those supported by
the base class, plus a few more. The commands are case
insensitive, but are usually capitalized. The number of data sets
to be plotted does not need to be specified. Data sets are added as needed.
Each dataset can be optionally identified with
color (see the base class) or with unique marks. The style of
marks used to denote a data point is defined by one of the following
commands:
Marks: none
Marks: points
Marks: dots
Marks: various
Here, "points" are small dots, while "dots" are larger. If "various"
is specified, then unique marks are used for the first ten data sets,
and then recycled.
Using no marks is useful when lines connect the points in a plot,
which is done by default.
If the above directive appears before any DataSet directive, then it
specifies the default for all data sets. If if appears after a DataSet
directive, then it applies only to that data set.
To disable connecting lines, use:
Lines: off
To reenable them, use
Lines: on
You can also specify "impulses", which are lines drawn from a plotted point
down to the x axis. Plots with impulses are often called "stem plots."
These are off by default, but can be turned on with the
command:
Impulses: on
or back off with the command
Impulses: off
If that command appears before any DataSet directive, then the command
applies to all data sets. Otherwise, it applies only to the current data
set.
To create a bar graph, turn off lines and use any of the following commands:
Bars: on
Bars: width
Bars: width, offset
The width is a real number specifying the width of the bars
in the units of the x axis. The offset is a real number
specifying how much the bar of the ith data set
is offset from the previous one. This allows bars to "peek out"
from behind the ones in front. Note that the frontmost data set
will be the last one. To turn off bars, use
Bars: off
To specify data to be plotted, start a data set with the following command:
DataSet: string
Here, string is a label that will appear in the legend.
It is not necessary to enclose the string in quotation marks.
To start a new dataset without giving it a name, use:
DataSet:
In this case, no item will appear in the legend.
New datasets are plotted behind the previous ones.
If the following directive occurs:
ReuseDataSets: on
Then datasets with the same name will be merged. This makes it
easier to combine multiple datafiles that contain the same datasets
into one file. By default, this capability is turned off, so
datasets with the same name are not merged.
The data itself is given by a sequence of commands with one of the
following forms:
x, y
draw: x, y
move: x, y
x, y, yLowErrorBar, yHighErrorBar
draw: x, y, yLowErrorBar, yHighErrorBar
move: x, y, yLowErrorBar, yHighErrorBar
The "draw" command is optional, so the first two forms are equivalent.
The "move" command causes a break in connected points, if lines are
being drawn between points. The numbers x and y are
arbitrary numbers as supported by the Double parser in Java.
If there are four numbers, then the last two numbers are assumed to
be the lower and upper values for error bars.
The numbers can be separated by commas, spaces or tabs.
This plotter has some limitations:
- If you zoom in far enough, the plot becomes unreliable.
In particular, if the total extent of the plot is more than
232 times extent of the visible area, quantization
errors can result in displaying points or lines.
Note that 232 is over 4 billion.
- The limitations of the log axis facility are listed in
the
_gridInit()
method in the PlotBox class.
- The compatibility issues of the
pxgraph
script are
list in the
Pxgraph
class.
- Version:
- $Id: Plot.java,v 1.122 1998/11/23 17:47:01 cxh Exp $
- Author:
- Edward A. Lee, Christopher Hylands
-
_currentdataset
-
-
_marks
-
-
_painted
-
-
_points
-
-
Plot()
-
-
_checkDatasetIndex(int)
- Check the argument to ensure that it is a valid data set index.
-
_drawBar(Graphics, int, long, long, boolean)
- Draw bar from the specified point to the y axis.
-
_drawErrorBar(Graphics, int, long, long, long, boolean)
- Draw an error bar for the specified yLowEB and yHighEB values.
-
_drawImpulse(Graphics, long, long, boolean)
- Draw a line from the specified point to the y axis.
-
_drawLine(Graphics, int, long, long, long, long, boolean)
- Draw a line from the specified starting point to the specified
ending point.
-
_drawPlot(Graphics, boolean)
- Draw the axes and then plot all points.
-
_drawPoint(Graphics, int, long, long, boolean)
- Put a mark corresponding to the specified dataset at the
specified x and y position.
-
_parseLine(String)
- Parse a line that gives plotting information.
-
_write(PrintWriter)
- Write plot information to the specified output stream.
-
addLegend(int, String)
- Add a legend (displayed at the upper right) for the specified
data set with the specified string.
-
addPoint(int, double, double, boolean)
- In the specified data set, add the specified x, y point to the
plot.
-
addPointWithErrorBars(int, double, double, double, double, boolean)
- In the specified data set, add the specified x, y point to the
plot with error bars.
-
clear(boolean)
- Clear the plot of all data points.
-
erasePoint(int, int)
- Erase the point at the given index in the given dataset.
-
fillPlot()
- Rescale so that the data that is currently plotted just fits.
-
getCmdLineFilename()
- Return the last file name seen on the command-line arguments parsed
by parseArgs().
-
getMaxDataSets()
- Return the maximum number of data sets.
Deprecated.
-
paint(Graphics)
- Start a new thread to paint the component contents.
-
parseArgs(String[])
- Parse pxgraph style command line arguments.
-
parseFile(String, URL)
- Override the base class to indicate that a new data set is being read.
Deprecated.
-
parsePxgraphargs(String)
- Split a string containing pxgraph-compatible command-line arguments
into an array and call parseArgs() on the array.
-
read(InputStream)
- Override the base class to register that we are reading a new
data set.
-
readPxgraph(InputStream)
- Read a pxgraph-compatible binary encoded file.
-
setBars(boolean)
- Turn bars on or off (for bar charts).
-
setBars(double, double)
- Turn bars on and set the width and offset.
-
setConnected(boolean)
- If the argument is true, then the default is to connect
subsequent points with a line.
-
setImpulses(boolean)
- If the argument is true, then a line will be drawn from any
plotted point down to the x axis.
-
setImpulses(boolean, int)
- If the first argument is true, then a line will be drawn from any
plotted point in the specified dataset down to the x axis.
-
setMarksStyle(String)
- Set the marks style to "none", "points", "dots", or "various".
-
setMarksStyle(String, int)
- Set the marks style to "none", "points", "dots", or "various"
for the specified dataset.
-
setNumSets(int)
- Specify the number of data sets to be plotted together.
Deprecated.
-
setPointsPersistence(int)
- Calling this method with a positive argument sets the
persistence of the plot to the given number of points.
-
setSweepsPersistence(int)
- A sweep is a sequence of points where the value of X is
increasing.
-
update(Graphics)
- Override the base class to not clear the component first.
_currentdataset
protected int _currentdataset
_points
protected Vector _points
_marks
protected int _marks
_painted
protected boolean _painted
Plot
public Plot()
addLegend
public void addLegend(int dataset,
String legend)
- Add a legend (displayed at the upper right) for the specified
data set with the specified string. Short strings generally
fit better than long strings.
- Parameters:
- dataset - The dataset index.
- legend - The label for the dataset.
- Overrides:
- addLegend in class PlotBox
addPoint
public synchronized void addPoint(int dataset,
double x,
double y,
boolean connected)
- In the specified data set, add the specified x, y point to the
plot. Data set indices begin with zero. If the data set
does not exist, create it. The fourth argument indicates
whether the point should be connected by a line to the previous
point. The new point will be made visible if the plot is visible
on the screen. Otherwise, it will be drawn the next time the plot
is drawn on the screen.
- Parameters:
- dataset - The data set index.
- x - The X position of the new point.
- y - The Y position of the new point.
- connected - If true, a line is drawn to connect to the previous
point.
addPointWithErrorBars
public synchronized void addPointWithErrorBars(int dataset,
double x,
double y,
double yLowEB,
double yHighEB,
boolean connected)
- In the specified data set, add the specified x, y point to the
plot with error bars. Data set indices begin with zero. If
the dataset does not exist, create it. yLowEB and
yHighEB are the lower and upper error bars. The sixth argument
indicates whether the point should be connected by a line to
the previous point.
The new point will be made visible if the plot is visible
on the screen. Otherwise, it will be drawn the next time the plot
is drawn on the screen.
This method is based on a suggestion by
Michael Altmann .
- Parameters:
- dataset - The data set index.
- x - The X position of the new point.
- y - The Y position of the new point.
- yLowEB - The low point of the error bar.
- yHighEB - The high point of the error bar.
- connected - If true, a line is drawn to connect to the previous
point.
clear
public synchronized void clear(boolean format)
- Clear the plot of all data points. If the argument is true, then
reset all parameters to their initial conditions, including
the persistence, plotting format, and axes formats.
For the change to take effect, you must call repaint().
- Parameters:
- format - If true, clear the format controls as well.
- Overrides:
- clear in class PlotBox
erasePoint
public synchronized void erasePoint(int dataset,
int index)
- Erase the point at the given index in the given dataset. If
lines are being drawn, also erase the line to the next points
(note: not to the previous point). The point is not checked to
see whether it is in range, so care must be taken by the caller
to ensure that it is.
The change will be made visible if the plot is visible
on the screen. Otherwise, it will take effect the next time the plot
is drawn on the screen.
- Parameters:
- dataset - The data set index.
- index - The index of the point to erase.
fillPlot
public synchronized void fillPlot()
- Rescale so that the data that is currently plotted just fits.
This overrides the base class method to ensure that the protected
variables _xBottom, _xTop, _yBottom, and _yTop are valid.
This method calls repaint(), which eventually causes the display
to be updated.
- Overrides:
- fillPlot in class PlotBox
getCmdLineFilename
public String getCmdLineFilename()
- Return the last file name seen on the command-line arguments parsed
by parseArgs(). If there was none, return null.
- Returns:
- A file name, or null if there is none.
getMaxDataSets
public int getMaxDataSets()
- Note: getMaxDataSets() is deprecated.
- Return the maximum number of data sets.
This method is deprecated, since there is no longer an upper bound.
paint
public void paint(Graphics graphics)
- Start a new thread to paint the component contents.
This is done in a new thread so that large data sets can
can be displayed without freezing the user interface.
When repainting is completed, the protected variable _painted
is set to true, and notifyAll() is called.
- Parameters:
- graphics - The graphics context.
- Overrides:
- paint in class PlotBox
parseArgs
public int parseArgs(String args[]) throws CmdLineArgException, FileNotFoundException, IOException
- Parse pxgraph style command line arguments.
This method exists only for backward compatibility with the X11 pxgraph
program.
- Parameters:
- args - A set of command-line arguments.
- Returns:
- The number of arguments read.
- Throws: CmdLineArgException
- If there is a problem parsing
the command line arguments.
- Throws: FileNotFoundException
- If a file is specified that is not
found.
- Throws: IOException
- If an error occurs reading an input file.
parseFile
public void parseFile(String filespec,
URL documentBase)
- Note: parseFile() is deprecated.
- Override the base class to indicate that a new data set is being read.
This method is deprecated. Use read() or readPxgraph() instead.
- Overrides:
- parseFile in class PlotBox
parsePxgraphargs
public int parsePxgraphargs(String pxgraphargs) throws CmdLineArgException, FileNotFoundException, IOException
- Split a string containing pxgraph-compatible command-line arguments
into an array and call parseArgs() on the array. This is used
in the rare circumstance that you want to control the format
of a plot from an applet HTML file rather than in the plot data
file.
- Returns:
- The number of arguments read.
- Throws: CmdLineArgException
- If there is a problem parsing
the command line arguments.
- Throws: FileNotFoundException
- If a file is specified that is not
found.
- Throws: IOException
- If an error occurs reading an input file.
read
public void read(InputStream in) throws IOException
- Override the base class to register that we are reading a new
data set.
- Parameters:
- inputstream - The input stream.
- Overrides:
- read in class PlotBox
readPxgraph
public void readPxgraph(InputStream inputstream) throws IOException
- Read a pxgraph-compatible binary encoded file.
- Parameters:
- in - The input stream.
- Throws: IOException
- If an I/O error occurs.
setBars
public void setBars(boolean on)
- Turn bars on or off (for bar charts).
- Parameters:
- on - If true, turn bars on.
setBars
public void setBars(double width,
double offset)
- Turn bars on and set the width and offset. Both are specified
in units of the x axis. The offset is the amount by which the
ith data set is shifted to the right, so that it
peeks out from behind the earlier data sets.
- Parameters:
- width - The width of the bars.
- offset - The offset per data set.
setConnected
public void setConnected(boolean on)
- If the argument is true, then the default is to connect
subsequent points with a line. If the argument is false, then
points are not connected. When points are by default
connected, individual points can be not connected by giving the
appropriate argument to addPoint().
setImpulses
public void setImpulses(boolean on)
- If the argument is true, then a line will be drawn from any
plotted point down to the x axis. Otherwise, this feature is
disabled. A plot with such lines is also known as a stem plot.
- Parameters:
- on - If true, draw a stem plot.
setImpulses
public void setImpulses(boolean on,
int dataset)
- If the first argument is true, then a line will be drawn from any
plotted point in the specified dataset down to the x axis.
Otherwise, this feature is
disabled. A plot with such lines is also known as a stem plot.
- Parameters:
- on - If true, draw a stem plot.
- dataset - The dataset to which this should apply.
setMarksStyle
public void setMarksStyle(String style)
- Set the marks style to "none", "points", "dots", or "various".
In the last case, unique marks are used for the first ten data
sets, then recycled.
- Parameters:
- style - A string specifying the style for points.
setMarksStyle
public void setMarksStyle(String style,
int dataset)
- Set the marks style to "none", "points", "dots", or "various"
for the specified dataset.
In the last case, unique marks are used for the first ten data
sets, then recycled.
- Parameters:
- style - A string specifying the style for points.
- dataset - The dataset to which this should apply.
setNumSets
public void setNumSets(int numsets)
- Note: setNumSets() is deprecated.
- Specify the number of data sets to be plotted together.
This method is deprecated, since it is no longer necessary to
specify the number of data sets ahead of time.
It has the effect of clearing all previously plotted points.
This method should be called before setPointsPersistence().
This method throws IllegalArgumentException if the number is less
than 1. This is a runtime exception, so it need not be declared.
- Parameters:
- numsets - The number of data sets.
setPointsPersistence
public void setPointsPersistence(int persistence)
- Calling this method with a positive argument sets the
persistence of the plot to the given number of points. Calling
with a zero argument turns off this feature, reverting to
infinite memory (unless sweeps persistence is set). If both
sweeps and points persistence are set then sweeps take
precedence.
setSweepsPersistence
public void setSweepsPersistence(int persistence)
- A sweep is a sequence of points where the value of X is
increasing. A point that is added with a smaller x than the
previous point increments the sweep count. Calling this method
with a non-zero argument sets the persistence of the plot to
the given number of sweeps. Calling with a zero argument turns
off this feature. If both sweeps and points persistence are
set then sweeps take precedence.
This feature is not implemented yet, so this method has no
effect.
update
public void update(Graphics g)
- Override the base class to not clear the component first.
- Parameters:
- graphics - The graphics context.
- Overrides:
- update in class Container
_checkDatasetIndex
protected void _checkDatasetIndex(int dataset)
- Check the argument to ensure that it is a valid data set index.
If it is less than zero, throw an IllegalArgumentException (which
is a runtime exception). If it does not refer to an existing
data set, then fill out the _points Vector so that it does refer
to an existing data set. All other dataset-related vectors are
similarly filled out.
- Parameters:
- dataset - The data set index.
_drawBar
protected void _drawBar(Graphics graphics,
int dataset,
long xpos,
long ypos,
boolean clip)
- Draw bar from the specified point to the y axis.
If the specified point is below the y axis or outside the
x range, do nothing. If the clip argument is true,
then do not draw above the y range.
Note that paint() should be called before
calling this method so that _xscale and _yscale are properly set.
- Parameters:
- graphics - The graphics context.
- dataset - The index of the dataset.
- xpos - The x position.
- ypos - The y position.
- clip - If true, then do not draw outside the range.
_drawErrorBar
protected void _drawErrorBar(Graphics graphics,
int dataset,
long xpos,
long yLowEBPos,
long yHighEBPos,
boolean clip)
- Draw an error bar for the specified yLowEB and yHighEB values.
If the specified point is below the y axis or outside the
x range, do nothing. If the clip argument is true,
then do not draw above the y range.
- Parameters:
- graphics - The graphics context.
- dataset - The index of the dataset.
- xpos - The x position.
- yLowEBPos - The lower y position of the error bar.
- yHighEBPos - The upper y position of the error bar.
- clip - If true, then do not draw above the range.
_drawImpulse
protected void _drawImpulse(Graphics graphics,
long xpos,
long ypos,
boolean clip)
- Draw a line from the specified point to the y axis.
If the specified point is below the y axis or outside the
x range, do nothing. If the clip argument is true,
then do not draw above the y range.
- Parameters:
- graphics - The graphics context.
- xpos - The x position.
- ypos - The y position.
- clip - If true, then do not draw outside the range.
_drawLine
protected void _drawLine(Graphics graphics,
int dataset,
long startx,
long starty,
long endx,
long endy,
boolean clip)
- Draw a line from the specified starting point to the specified
ending point. The current color is used. If the clip argument
is true, then draw only that portion of the line that lies within the
plotting rectangle.
- Parameters:
- graphics - The graphics context.
- dataset - The index of the dataset.
- startx - The starting x position.
- starty - The starting y position.
- endx - The ending x position.
- endy - The ending y position.
- clip - If true, then do not draw outside the range.
_drawPlot
protected synchronized void _drawPlot(Graphics graphics,
boolean clearfirst)
- Draw the axes and then plot all points. This is synchronized
to prevent multiple threads from drawing the plot at the same
time. It sets _painted true and calls notifyAll() at the end so that a
thread can use
wait()
to prevent it plotting
points before the axes have been first drawn. If the second
argument is true, clear the display first.
This method is called by paint(). To cause it to be called you
would normally call repaint(), which eventually causes paint() to
be called.
- Parameters:
- graphics - The graphics context.
- clearfirst - If true, clear the plot before proceeding.
- Overrides:
- _drawPlot in class PlotBox
_drawPoint
protected void _drawPoint(Graphics graphics,
int dataset,
long xpos,
long ypos,
boolean clip)
- Put a mark corresponding to the specified dataset at the
specified x and y position. The mark is drawn in the current
color. What kind of mark is drawn depends on the _marks
variable and the dataset argument. If the fourth argument is
true, then check the range and plot only points that
are in range.
- Parameters:
- graphics - The graphics context.
- dataset - The index of the dataset.
- xpos - The x position.
- ypos - The y position.
- clip - If true, then do not draw outside the range.
- Overrides:
- _drawPoint in class PlotBox
_parseLine
protected boolean _parseLine(String line)
- Parse a line that gives plotting information. Return true if
the line is recognized. Lines with syntax errors are ignored.
- Parameters:
- line - A command line.
- Returns:
- True if the line is recognized.
- Overrides:
- _parseLine in class PlotBox
_write
protected void _write(PrintWriter output)
- Write plot information to the specified output stream.
Derived classes should override this method to first call
the parent class method, then add whatever additional information
they wish to add to the stream.
- Parameters:
- output - A buffered print writer.
- Overrides:
- _write in class PlotBox
All Packages Class Hierarchy This Package Previous Next Index