jhplot

Class SPlot

java.lang.Object

jhplot.SPlot

public class SPlot
extends java.lang.Object

A class to build a simple canvas with data points. Based on PTOLEMY package. This class is simpler than HPlot class, and has a low memory consumption.

Constructor Summary

Constructors

Constructor and Description
SPlot() Construct a frame with a canvas.
SPlot(java.io.File f) Construct a frame with a canvas and open XML file with the data.
SPlot(int width, int height) Construct a frame with the plot.
SPlot(java.lang.String title, int width, int height) Construct a frame with the plot.

Method Summary

Modifier and Type	Method and Description
void	addLegend(int dataset, java.lang.String legend) Add a legend (displayed at the upper right) for the specified data set with the specified string.
void	addPoint(int dataset, double x, double y, boolean connected) In the specified data set, add the specified x, y point to the plot.
void	addPointErr(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.
void	addXTick(java.lang.String label, double position) Specify a tick mark for the X axis.
void	addYTick(java.lang.String label, double position) Specify a tick mark for the Y axis.
void	clear() Clear the plot of all data points.
void	clear(int dataset) Clear the plot of data points in the specified dataset.
void	clearLegends() Clear all legends.
void	doc() Show online documentation.
void	draw(double[][] x, double[][] y) Draw multiple sets as marks (default).
void	draw(double[] x, double[] y) Draw a single data set as marks (default).
void	draw(H1D h1) Draw H1D histograms
void	draw(P1D p1d) Draw P1D object.
void	draw(java.lang.String[] legend, double[][] x, double[][] y) Set sets of data with legends
void	draw(java.lang.String legend, double[] x, double[] y) Draw a single data set with a legend.
void	draw(java.lang.String legend, double[] x, double[] y, double[] ey) Draw a single data set with errors on Y with legend.
void	erasePoint(int dataset, int index) Erase the point at the given index in the given dataset.
void	export(java.lang.String f) Fast export of the canvas to an image file (depends on the extension, i.e.
void	fillPlot() Rescale so that the data that is currently plotted just fits.
java.awt.Color[]	getColors() Get the point colors.
double[][]	getData(int index) Get the data in the specified dataset.
boolean	getGrid() Return whether the grid is drawn.
java.lang.String	getLegend(int dataset) Get the legend for a dataset, or null if there is none.
int	getLegendDataset(java.lang.String legend) Given a legend string, return the corresponding dataset or -1 if no legend was added with that legend string.
int	getNumDataSets() Return the actual number of data sets.
java.awt.Rectangle	getPlotRectangle() Get the current plot rectangle.
java.lang.String	getTitle() Get the title of the graph, or an empty string if there is none.
double[]	getXAutoRange() Get the range for X values of the data points registered so far.
java.lang.String	getXLabel() Get the label for the X (horizontal) axis, or null if none has been set.
boolean	getXLog() Return whether the X axis is drawn with a logarithmic scale.
double[]	getXRange() Get the X range.
java.util.Vector[]	getXTicks() Get the X ticks that have been specified, or null if none.
double[]	getYAutoRange() Get the range for Y values of the data points registered so far.
java.lang.String	getYLabel() Get the label for the Y (vertical) axis, or null if none has been set.
boolean	getYLog() Return whether the Y axis is drawn with a logarithmic scale.
double[]	getYRange() Get the Y range.
java.util.Vector[]	getYTicks() Get the Y ticks that have been specified, or null if none.
static void	main(java.lang.String[] args)
void	read(java.io.File file) Read a XML file and build a plot
void	read(java.lang.String file) Read a XML file and build a plot
void	renameLegend(int dataset, java.lang.String newName) Rename a legend.
void	resetAxes() Reset the X and Y axes to the ranges that were first specified using setXRange() and setYRange().
void	setAutoRange() Rescale so that the data that is currently plotted just fits.
void	setAutoRange(boolean auto) Rescale so that the data that is currently plotted just fits.
void	setBackground(java.awt.Color c) Set background for the plot.
void	setBars(boolean on) Turn bars on or off (for bar charts).
void	setBars(double width, double offset) Turn bars on and set the width and offset.
void	setBounds(int x, int y, int width, int height) Move and resize this component.
void	setColor(boolean useColor) If the argument is false, draw the plot without using color (in black and white).
void	setColors(java.awt.Color[] colors) Set the point colors.
void	setConnected(boolean on, int dataset) If the first argument is true, then by default for the specified dataset, points will be connected by a line.
void	setEditable(int index) Specify which dataset is editable.
void	setForeground(java.awt.Color foreground) Set the foreground color.
void	setGrid(boolean grid) Control whether the grid is drawn.
void	setGTitle(java.lang.String title) Set global title for this plot.
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.
void	setLabelFont(java.lang.String name) Set the label font, which is used for axis labels and legend labels.
void	setMarksStyle(java.lang.String style) Set the marks style to "none", "points", "dots", or "various".
void	setMarksStyle(java.lang.String style, int dataset) Set the marks style to "none", "points", "dots", "various", or "pixels" for the specified dataset.
void	setNameX(java.lang.String label) Set the label for the X (horizontal) axis.
void	setNameY(java.lang.String label) Set the label for the Y (vertical) axis.
void	setRange(double xmin, double xmax, double ymin, double ymax) Set range for X and Y axes.
void	setSize(int width, int height) Set size of the frame.
void	setTitle(java.lang.String title) Set global title for this plot.
void	setTitleFont(java.lang.String name) Set the title font.
void	setWrap(boolean wrap) Specify whether the X axis is wrapped.
void	setXLog(boolean xlog) Specify whether the X axis is drawn with a logarithmic scale.
void	setXRange(double min, double max) Set the X (horizontal) range of the plot.
void	setYLog(boolean ylog) Specify whether the Y axis is drawn with a logarithmic scale.
void	setYRange(double min, double max) Set the Y (vertical) range of the plot.
void	update() Repaint the plot and update all graphics.
void	visible() Show the frame.
void	visible(boolean showIt) Show or not the frame
void	visible(int posX, int posY) Set the canvas frame visible.
void	write(java.lang.String file) Write the current plot to a XML file
void	zoom(double lowx, double lowy, double highx, double highy) Zoom in or out to the specified rectangle.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SPlot

public SPlot()

Construct a frame with a canvas. Default: do not show it.

SPlot

public SPlot(java.io.File f)

Construct a frame with a canvas and open XML file with the data. Default: do not show it.

Parameters:

f - file to read.

SPlot

public SPlot(int width,
             int height)

Construct a frame with the plot. Do not show it.

Parameters:

width - frame width

height - frame height

SPlot

public SPlot(java.lang.String title,
             int width,
             int height)

Construct a frame with the plot. Do not show it.

Parameters:

title - i Title

width - frame width

height - frame height

Method Detail

setSize

public void setSize(int width,
                    int height)

Set size of the frame.

Parameters:

width - frame width

height - frame height

setEditable

public void setEditable(int index)

Specify which dataset is editable.

Parameters:

index - index of data set

getData

public double[][] getData(int index)

Get the data in the specified dataset.

Parameters:

index - index of data set

Returns:

plotted data

setBackground

public void setBackground(java.awt.Color c)

Set background for the plot.

Parameters:

c - background color.

setGTitle

public void setGTitle(java.lang.String title)

Set global title for this plot.

Parameters:

title - plot title

setTitle

public void setTitle(java.lang.String title)

Set global title for this plot.

Parameters:

title - plot title

setRange

public void setRange(double xmin,
                     double xmax,
                     double ymin,
                     double ymax)

Set range for X and Y axes.

Parameters:

xmin - Min for X

xmax - Max for X

ymin - Min for Y

ymax - Max for Y

addLegend

public void addLegend(int dataset,
                      java.lang.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. If the string is empty, or the argument is null, then no legend is added.

Parameters:

dataset - The dataset index.

legend - The label for the dataset.

See Also:

renameLegend(int, String)

addXTick

public void addXTick(java.lang.String label,
                     double position)

Specify a tick mark for the X axis. The label given is placed on the axis at the position given by position. If this is called once or more, automatic generation of tick marks is disabled. The tick mark will appear only if it is within the X range.

Parameters:

label - The label for the tick mark.

position - The position on the X axis.

addYTick

public void addYTick(java.lang.String label,
                     double position)

Specify a tick mark for the Y axis. The label given is placed on the axis at the position given by position. If this is called once or more, automatic generation of tick marks is disabled. The tick mark will appear only if it is within the Y range.

Parameters:

label - The label for the tick mark.

position - The position on the Y axis.

clear

public void clear()

Clear the plot of all data points.

clearLegends

public void clearLegends()

Clear all legends. This will show up on the next redraw.

getColors

public java.awt.Color[] getColors()

Get the point colors.

Returns:

Array of colors

See Also:

setColors(Color[])

getGrid

public boolean getGrid()

Return whether the grid is drawn.

Returns:

True if a grid is drawn.

getLegend

public java.lang.String getLegend(int dataset)

Get the legend for a dataset, or null if there is none.

Parameters:

dataset - The dataset index.

Returns:

The legend label, or null if there is none.

getLegendDataset

public int getLegendDataset(java.lang.String legend)

Given a legend string, return the corresponding dataset or -1 if no legend was added with that legend string.

Parameters:

legend - The String naming the legend

Returns:

The legend dataset, or -1 if not found.

getPlotRectangle

public java.awt.Rectangle getPlotRectangle()

Get the current plot rectangle. Note that Rectangle returned by this method is calculated from the values. The value passed in by setPlotRectangle() is not directly used, thus calling getPlotRectangle() may not return the same rectangle that was passed in with setPlotRectangle().

Returns:

Rectangle

getTitle

public java.lang.String getTitle()

Get the title of the graph, or an empty string if there is none.

Returns:

The title.

getXAutoRange

public double[] getXAutoRange()

Get the range for X values of the data points registered so far. Usually, derived classes handle managing the range by checking each new point against the current range.

Returns:

An array of two doubles where the first element is the minimum and the second element is the maximum.

See Also:

getXRange()

setColor

public void setColor(boolean useColor)

If the argument is false, draw the plot without using color (in black and white). Otherwise, draw it in color (the default).

Parameters:

useColor - False to draw in back and white.

setColors

public void setColors(java.awt.Color[] colors)

Set the point colors. Note that the default colors have been carefully selected to maximize readability and that it is easy to use colors that result in a very ugly plot.

Parameters:

colors - Array of colors to use in succession for data sets.

See Also:

getColors()

setForeground

public void setForeground(java.awt.Color foreground)

Set the foreground color.

Parameters:

foreground - The foreground color.

setGrid

public void setGrid(boolean grid)

Control whether the grid is drawn.

Parameters:

grid - If true, a grid is drawn.

setLabelFont

public void setLabelFont(java.lang.String name)

Set the label font, which is used for axis labels and legend labels. The font names understood are those understood by java.awt.Font.decode().

Parameters:

name - A font name.

getXLabel

public java.lang.String getXLabel()

Get the label for the X (horizontal) axis, or null if none has been set.

Returns:

The X label.

getXLog

public boolean getXLog()

Return whether the X axis is drawn with a logarithmic scale.

Returns:

True if the X axis is logarithmic.

getXRange

public double[] getXRange()

Get the X range. This method returns the values passed in as arguments to setXRange(double, double). If setXRange(double, double) has not been called, then this method returns the range of the data to be plotted, which might not be all of the data due to zooming.

Returns:

An array of two doubles where the first element is the minimum and the second element is the maximum.

See Also:

getXAutoRange()

getXTicks

public java.util.Vector[] getXTicks()

Get the X ticks that have been specified, or null if none. The return value is an array with two vectors, the first of which specifies the X tick locations (as instances of Double), and the second of which specifies the corresponding labels.

Returns:

The X ticks.

getYAutoRange

public double[] getYAutoRange()

Get the range for Y values of the data points registered so far. Usually, derived classes handle managing the range by checking each new point against the range.

Returns:

An array of two doubles where the first element is the minimum and the second element is the maximum.

See Also:

getYRange()

getYLabel

public java.lang.String getYLabel()

Get the label for the Y (vertical) axis, or null if none has been set.

Returns:

The Y label.

getYLog

public boolean getYLog()

Return whether the Y axis is drawn with a logarithmic scale.

Returns:

True if the Y axis is logarithmic.

getYRange

public double[] getYRange()

Get the Y range. If setYRange(double, double) has been called, then this method returns the values passed in as arguments to setYRange(double, double). If setYRange(double, double) has not been called, then this method returns the range of the data to be plotted, which might not be all of the data due to zooming.

Returns:

An array of two doubles where the first element is the minimum and the second element is the maximum.

See Also:

getYAutoRange()

getYTicks

public java.util.Vector[] getYTicks()

Get the Y ticks that have been specified, or null if none. The return value is an array with two vectors, the first of which specifies the Y tick locations (as instances of Double), and the second of which specifies the corresponding labels.

Returns:

The Y ticks.

renameLegend

public void renameLegend(int dataset,
                         java.lang.String newName)

Rename a legend.

Parameters:

dataset - The dataset of the legend to be renamed. If there is no dataset with this value, then nothing happens.

newName - The new name of legend.

See Also:

addLegend(int, String)

resetAxes

public void resetAxes()

Reset the X and Y axes to the ranges that were first specified using setXRange() and setYRange(). If these methods have not been called, then reset to the default ranges. This method calls repaint(), which eventually causes the display to be updated.

setBounds

public void setBounds(int x,
                      int y,
                      int width,
                      int height)

Move and resize this component. The new location of the top-left corner is specified by x and y, and the new size is specified by width and height. This overrides the base class method to make a record of the new size.

Parameters:

x - The new x-coordinate of this component.

y - The new y-coordinate of this component.

width - The new width of this component.

height - The new height of this component.

setTitleFont

public void setTitleFont(java.lang.String name)

Set the title font. The font names understood are those understood by java.awt.Font.decode().

Parameters:

name - A font name.

setWrap

public void setWrap(boolean wrap)

Specify whether the X axis is wrapped. If it is, then X values that are out of range are remapped to be in range using modulo arithmetic. The X range is determined by the most recent call to setXRange() (or the most recent zoom). If the X range has not been set, then use the default X range, or if data has been plotted, then the current fill range.

Parameters:

wrap - If true, wrapping of the X axis is enabled.

setNameX

public void setNameX(java.lang.String label)

Set the label for the X (horizontal) axis.

Parameters:

label - The label.

setXLog

public void setXLog(boolean xlog)

Specify whether the X axis is drawn with a logarithmic scale. If you would like to have the X axis drawn with a logarithmic axis, then setXLog(true) should be called before adding any data points.

Parameters:

xlog - If true, logarithmic axis is used.

setXRange

public void setXRange(double min,
                      double max)

Set the X (horizontal) range of the plot. If this is not done explicitly, then the range is computed automatically from data available when the plot is drawn. If min and max are identical, then the range is arbitrarily spread by 1.

Parameters:

min - The left extent of the range.

max - The right extent of the range.

setNameY

public void setNameY(java.lang.String label)

Set the label for the Y (vertical) axis.

Parameters:

label - The label.

setYLog

public void setYLog(boolean ylog)

Specify whether the Y axis is drawn with a logarithmic scale. If you would like to have the Y axis drawn with a logarithmic axis, then setYLog(true) should be called before adding any data points.

Parameters:

ylog - If true, logarithmic axis is used.

setYRange

public void setYRange(double min,
                      double max)

Set the Y (vertical) range of the plot. If this is not done explicitly, then the range is computed automatically from data available when the plot is drawn. If min and max are identical, then the range is arbitrarily spread by 0.1.

Parameters:

min - The bottom extent of the range.

max - The top extent of the range.

zoom

public void zoom(double lowx,
                 double lowy,
                 double highx,
                 double highy)

Zoom in or out to the specified rectangle. This method calls repaint().

Parameters:

lowx - The low end of the new X range.

lowy - The low end of the new Y range.

highx - The high end of the new X range.

highy - The high end of the new Y range.

write

public void write(java.lang.String file)

Write the current plot to a XML file

Parameters:

file - File name

read

public void read(java.lang.String file)

Read a XML file and build a plot

Parameters:

file - File name to read

read

public void read(java.io.File file)

Read a XML file and build a plot

Parameters:

file - File name to read

draw

public void draw(double[][] x,
                 double[][] y)

Draw multiple sets as marks (default).

Parameters:

x - array of x

y - array of y

draw

public void draw(double[] x,
                 double[] y)

Draw a single data set as marks (default).

Parameters:

x - array of x values

y - array of y values

draw

public void draw(java.lang.String legend,
                 double[] x,
                 double[] y)

Draw a single data set with a legend.

Parameters:

legend - legend to show

x - array of x values

y - array of y values

draw

public void draw(java.lang.String legend,
                 double[] x,
                 double[] y,
                 double[] ey)

Draw a single data set with errors on Y with legend.

Parameters:

legend - legend to show

x - array of x values

y - array of y values

ey - array of errors on y values

clear

public void clear(int dataset)

Clear the plot of data points in the specified dataset. This calls repaint() to request an update of the display.

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the point will not be added immediately (unless you call this method from within the event dispatch thread). If you call this method, the addPoint() method, and the erasePoint() method in any order, they are assured of being processed in the order that you called them.

Parameters:

dataset - The dataset to clear.

erasePoint

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

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the point will not be erased immediately (unless you call this method from within the event dispatch thread). All the methods that do this deferring coordinate so that they are executed in the order that you called them.

Parameters:

dataset - The data set index.

index - The index of the point to erase.

fillPlot

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

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the fill will not occur immediately (unless you call this method from within the event dispatch thread). All the methods that do this deferring coordinate so that they are executed in the order that you called them.

setAutoRange

public void setAutoRange()

Rescale so that the data that is currently plotted just fits.

setAutoRange

public void setAutoRange(boolean auto)

Rescale so that the data that is currently plotted just fits.

Parameters:

auto - if true, then autorange

update

public void update()

Repaint the plot and update all graphics.

getNumDataSets

public int getNumDataSets()

Return the actual number of data sets.

Returns:

The number of data sets that have been created.

setBars

public void setBars(boolean on)

Turn bars on or off (for bar charts). Note that this is a global property, not per dataset.

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,
                         int dataset)

If the first argument is true, then by default for the specified dataset, points will be connected by a line. Otherwise, the points will not be connected. When points are by default connected, individual points can be not connected by giving the appropriate argument to addPoint(). Note that this method should be called before adding any points. Note further that this method should probably be called from the event thread.

Parameters:

on - If true, draw lines between points.

dataset - The dataset to which this should apply.

addPoint

public 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. Regardless of the value of this argument, a line will not drawn if either there has been no previous point for this dataset or setConnected() has been called with a false argument.

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the point will not be added immediately (unless you call this method from within the event dispatch thread). All the methods that do this deferring coordinate so that they are executed in the order that you called them.

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.

addPointErr

public void addPointErr(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 .

In order to work well with swing and be thread safe, this method actually defers execution to the event dispatch thread, where all user interface actions are performed. Thus, the point will not be added immediately (unless you call this method from within the event dispatch thread). All the methods that do this deferring coordinate so that they are executed in the order that you called them.

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.

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(java.lang.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. This method should be called only from the event dispatch thread.

Parameters:

style - A string specifying the style for points.

setMarksStyle

public void setMarksStyle(java.lang.String style,
                          int dataset)

Set the marks style to "none", "points", "dots", "various", or "pixels" 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.

draw

public void draw(H1D h1)

Draw H1D histograms

Parameters:

h1 - H1D histogram to be shown.

draw

public void draw(P1D p1d)

Draw P1D object. If errors are included to P1D, they will be shown.

Parameters:

p1d - P1D object to show

draw

public void draw(java.lang.String[] legend,
                 double[][] x,
                 double[][] y)

Set sets of data with legends

Parameters:

legend - array of legends

x - array of x

y - array of y

visible

public void visible(boolean showIt)

Show or not the frame

Parameters:

showIt - true if should be shown

visible

public void visible()

Show the frame.

visible

public void visible(int posX,
                    int posY)

Set the canvas frame visible. Also set its location.

Parameters:

posX - - the x-coordinate of the new location's top-left corner in the parent's coordinate space;

posY - - he y-coordinate of the new location's top-left corner in the parent's coordinate space

main

public static void main(java.lang.String[] args)

export

public void export(java.lang.String f)

Fast export of the canvas to an image file (depends on the extension, i.e. PNG, JPG, EPS, PS). No questions will be asked, an existing file will be rewritten

Parameters:

f - Output file with the proper extension. If no extension, PNG file is assumed.

doc

public void doc()

Show online documentation.