Chapter 6.
Using Data in your Chart
|
One of the first things you may want to do with Perspective for Java is import your own data into a chart. Perspective provides built-in sample data that will be used until and unless you set up your own data source. The sample data is used so you can insert the Bean or Applet into a development environment or web page and instantly see a chart without connecting your own data. |
|
|
Perspective for Java supports several methods for connecting your data. One of them will be the most useful for your own situation. The easiest method is to simply load the data from a text file on your server; the most complex is to set up a callback mechanism between Perspective for Java and your own Java applet. The current methods are: |
|
|
|
Load Data from a server-based text file |
|
|
Place data directly within your HTML page |
|
|
Load data using an SQL query to any JDBC/OCBC compliant database |
|
|
Pass a data object from another Java class or applet |
|
|
Register a data object within your own class to "feed" data automatically to Perspective for Java |
|
|
Set individual values for the chart within your Java code |
|
Part and parcel of the "data" are the strings for Title, Subtitle, Footnote, the various axis titles, and the strings for the Series (legend text) and Groups (bottom ordinal axes) of your chart. Some of these methods allow you to pass Series and Group labels along with the data, but all require that you separately set strings for the Titles. |
Text files are used by many web server applications. Any CGI or PERL script can create text files using the simple I/O types built-in, and many programmers like to collect their data into a text file in order to pass it along to the next application. Perspective for Java includes the ability to directly load any data text file, whether it was created via CGI or PERL methods or exported from a spreadsheet application. |
|
|
You can load any text file into a Perspective applet. This is done by using the setDataFileURL method, which takes as input any valid file location or Internet URL. The text file needs to be organized in "spreadsheet" fashion, with rows of number for series, and columns of numbers for groups. You can optionally supply row and/or column headers, which will then be used for labeling the series and groups on the graph. Each value must be separated by a comma, and each text value needs to be in quotes. However, if you ARE supplying row and column headers, the very first word in the file must be "labels", in quotes, separated by a comma. |
|
Here is an example of the contents of a valid data file. Files of this type are often referred to as Comma Separated Values (CSV) files. Excel (or any other spreadsheet application) can easily export data directly into this format: |
|
"labels", "March", "April", "May", "June", |
|
Here is the same file without the labels: |
|
300, 30, 33, 28, 39, 33, 49 |
|
You can replace it with any data you want and the function will work the same. Files can be any name, any length, any location, any number of values |
For a quick example of how to do this, select the View Source option on any of the "live demo" pages. The setDataSeries() method that is only available in HTML can be used to assign a list of real numbers to one or more series in a chart. The following example HTML file illustrates how this method is used to assign data values to a sequential set of series in a BiPolar chart: |
|
Example: |
<HTML><HEAD><TITLE>TDGChartApplet</TITLE></HEAD><BODY> |
The setDataFromSQL() method loads graph columns and rows in the given query. It creates a result set and closes the result set. |
||
|
|
setDataFromSQL(String SQLQuery, Statement aStmt) |
Example: |
{ |
|
|
The setDataFromResultSet() method loads graph columns and rows in the given result set. The result set is not closed. |
|
|
|
setDataFromResultSet(ResultSet rs): |
|
These support methods can be used to determine an SQL data type: |
|
|
|
isSQLTypeNumeric(int SQLType): This method returns a value that indicates whether or not SQLType is an SQL numeric data type. |
|
|
isSQLTypeString(int SQLType): This method returns a value that indicates whether or not SQLType is an SQL string data type. |
When loading data from Java, use one of these methods: |
||
|
|
The TDGDataGrid Interface |
|
|
The CallBack Technique (setDataFromCallBack()) |
|
|
Individual Values (setData ( row,column,value );) |
|
TDGDataGrid is series of methods that you must implement into an object. You can have any number of other methods or functions inside this object. See TDGDataGrid Methods in Chapter 10 for a description of the methods that must be included in the object. |
|
Perspective will get data from this object based on how your application implements these methods. It does not matter how you process, parse, or access your data. However, these methods must be made public so that Perspective can access them to retrieve data. |
|
For large data sets, you may also implement the optional TDGPreScaleIF interface that lets you define how minimum and maximum scaling values are handled. See Handling Large Data Sets with TDGPreScaleIF. |
Handling Large Data Sets with TDGPreScaleIF
|
TDGPreScaleIF is an optional callback interface that users with large datasets may implement in their existing data callbacks (TDGDataGrid) to expedite processing of data. See Chapter 10 for a description of the methods in this interface. |
The setDataFromCallback() method can be used to load data from a predefined data grid. The input parameter to this method identifies the data grid: |
||
|
|
setDataFromCallBack(TDGDataGrid grid) |
|
grid : This parameter should identify an interface that represents an abstract data model that is one way of preparing data |
|
|
setDataFromCallBack() can be used to enable the chart data to be slaved to an arbitrary Java Object which implements the TDGDataGrid Interface. When a "callback" is in effect and the chart needs to redraw itself, for instance, after a property is changed, the chart will query the "isDirty()" method of the Java Object. |
|
|
If the result is true, Perspective for Java will call several other methods on the Java Object to gather all of the data required to draw itself. The Java Object itself may be a remote object through Remote Method Invocation (RMI) or may obtain data through JDBC or by any other means as long as it implements the TDGDataGrid Interface. |
|
Example: |
void button2_Action(java.awt.event.ActionEvent event) |
Use these properties and methods to load data using individual values: |
||
|
|
UseSampleData(true/false) |
|
|
setData(int row, int col, double fValue): This method sets the data value for a series/group intersection. When this method is used to assign individual values to series and groups, the setDataRangeToExtent() method must be used after the last setData() in order for the data to be applied to the chart. If setDataRangeToExtent() is not used, Perspective will display the message "not enough data to draw chart". |
|
|
setSeriesLabel(int seriesID, String newValue) |
|
|
setGroupLabel(int groupID, String newValue) |
|
|
setDataRangeToExtent():This method sets the range of data to be used in the chart according to the number of values identified by the setData() method. It must be used after any setData() operations. |
|
The first thing to do is to turn off the sample data set. Do this by setting the property to false: |
|
|
setUseSampleData(false); |
|
|
To set a data cell to 100, for example, just set that to the proper row/col address. The first address is 0 for both. So, if we want to set the value 100 for the zero row and zero column (the first riser in the chart), do this: |
|
|
setData(0,0,100); |
|
|
To set the second item in the row (the next riser in the same series) to 132, do this: |
|
|
setData(0,1,132); |
|
|
A FOR loop can be used for an array of the whole data set in question. |
|
|
After all values have been set with setData(), use the following method to apply all the data to the chart. |
|
|
setDataRangeToExtent (); |
|
|
If setDataRangeToExtent() is not used, Perspective will display the message "not enough data to draw chart". |
|
|
For labels, there are series labels (usually thought of as "row labels") and group labels (usually thought of as "column labels"). Here, you need only specify the series or group number, plus the text string for the label. In the following example, the label for the zero series is set to "Fred": |
|
|
setSeriesLabel(0, "Fred"); |
|
|
The following example sets the group label for the zero group to "March": |
|
|
setGroupLabel(0, "March"); |
|
Regardless of the method you use to import data into the chart, these properties and methods help you set, clear, and manage data in the chart: |
|
|
|
clearDataLabels(): This method clears all labels from the look, not from the data. |
|
|
clearDataStorage(): This method clears all data storage in a chart. |
|
|
clearGroupLabels(): This method clears all group labels in a chart. |
|
|
clearSeriesLabels(): This method clears all series labels in a chart. |
|
|
DataItemsAlongSeries; This property determines whether data items are aligned parallel to the series (both rows or both columns). |
|
|
getChartDataValid(): This method determines whether or not chart data is valid. |
|
|
getDataAsDouble(int row, int col): This method gets the numeric value for any series/group intersection. |
|
|
getDataAsString(int row, int col): This method gets a value for any series/group intersection and converts it to a string. |
|
|
getDataCoord(IdentObj id): This method gets the coordinates of an object in a chart. |
|
|
getDataFromCoord(IdentObj id, int nCoordVC): This method gets a data value for an object at a specified coordinates in a chart. |
|
|
getDataValue(IdentObj id): This method gets a data value for a specific data object (riser) in a chart. |
|
|
InterpretAsHLOC; This property is included in Perspective to support backward compatibility with Open-Hi-Lo-Close datasets created for Three |D| Graphics Presentation Graphics Software Development Kit (PGSDK). |
|
|
setDataFileURL(String aDataFileURL): Set data from a URL. |
|
|
setDataFromDataGrid(TDGDataGrid grid): Set data using a predefined data grid. |
|
|
setDataLabel(int s, int g, String newValue); Set a data label for a series (s) and group (g). |
|
|
setDataRange(): This method is used to establish the range of data that will be used in a chart. |
|
|
setDataValue (IdentObj id, double newValue): This method sets a data value for a specific data object (riser) in a chart. |
These properties are used to define chart-wide titles: |
||
|
|
FootnoteString |
|
|
SubtitleString |
|
|
TitleString |
|
These properties are used to define chart axis titles: |
|
|
|
O1TitleString |
|
|
O2TitleString |
|
|
X1TitleString |
|
|
Y1TitleString |
|
|
Y2TitleString |
|
Regardless of the data that assigned to each series/group, the range of data that is imaged on a numeric axis can be limited by the {Axis}ScaleMin and {Axis}ScaleMax properties. For example, the sample data used for a simple vertical bar graph creates a chart in the following format: |
|
|
|
The Y1ScaleMax, Y1ScaleMaxAuto, Y1ScaleMin, and Y1ScaleMinAuto properties can be used to modify the range of values displayed on the Y1 axis as shown in the following example: |
Example: |
perspective1.setY1ScaleMaxAuto(false); |
|
When these properties are set, the chart is imaged in the following format: |
|
|
|
The setDataRange() method can be used to limit the number of series/groups (rows/columns) that are imaged in the chart. |
Example: |
setDataRange (1,1,3,3); |
|
|
|
The following properties can also be used to limit the range of data that is imaged in the chart: |
|
|
|
ScrollOffsetGroup: This property specifies the first group to be imaged in the chart. |
|
|
ScrollOffsetSeries: This property specifies the first series to be imaged in the chart. |
|
|
ViewableGroups: This property specifies the maximum number of groups to be imaged in the chart. |
|
|
ViewableGroupsStock: This property specifies the maximum number of groups to be imaged in a stock chart. |
|
|
ViewableSeries: This property specifies the maximum number of series to be imaged in the chart. |
|
|
ViewableSeriesStock: This property specifies the maximum number of series to be imaged in a stock chart. |
Example: |
perspective1.setDepthAngle(0); |
|
|
|
|
|
When the number of viewable groups or series is set to a value less than the number of groups/series in the data set that defines the chart, you can use these properties to display data scroll bars in the chart: |
|
|
|
DataScrollerPresenceGroups: This property controls the presence of data scroll bars on the group axis. When the number of viewable groups is set to a value less than the number of groups in the data set, the scroll bar can be used to change the first group in the chart that is displayed (i.e., effectively changes the value assigned to ScrollOffsetGroup). |
|
|
DataScrollerPresenceSeries: This property controls the presence of data scroll bars on the series axis. When the number of viewable series is set to a value less than the number of series in the data set, the scroll bar can be used to change the series group in the chart that is displayed (i.e., effectively changes the value assigned to ScrollOffsetSeries). |
Example: |
perspective1.setDataScrollerPresenceGroups(2); |
|
|
|
|
|
The data scroller bar consists of two segments: 1) a segment that can be used to click and drag to the first group to be displayed and 1) a status bar that shows the number of the first group (i.e., the ScrollOffsetGroup value), the total number of viewable groups, and the remaining number of groups in the data set. In the first segment, the darker, movable thumb can be dragged to change the group offset. In the second segment, the total of the three numbers indicates the total number of groups defined in the data set. For example, the status area of the scroll bar displays "2 3 1". These numbers indicate that ScrollOffsetGroup is "2", ViewableGroups is "3", there is "1" group in the data set that is not displayed, and there are a total of six groups defined in the data set. The user can click on these numbers and edit them with the arrow keys. |
|
The following properties and methods can be used to zoom in, zoom out, and identify data zooming parameters: |
|
|
|
clearZoomList(): This method clears all entries in the zoom list and returns the chart to its original un-zoomed state. |
|
|
doZoomIn(): This method can be used to zoom in on the center of the chart, a given point (in x,y virtual coordinates), or a rectangle. The ZoomPercentage property identifies the amount of zoom. |
|
|
doZoomOut(): This method can be used to zoom out on the center of the chart or a given point (in x,y virtual coordinates). The ZoomPercentage property identifies the amount of zoom. |
|
|
get/setZoomIndex(): This method gets/sets the current zoom state index. It sets the "level" of zooming to go to. Only values inside the current zoom index may be used. Use isValidZoomIndex() to determine if the zoom index value is valid. |
|
|
isValidZoomIndex( value ): This method returns true or false indicating whether or not value is a valid zoom index. |
|
|
isZoomingArmed(): This method returns true or false indicating whether or not at least one zooming operating has been performed on the chart. |
|
|
ZoomDirection: This property selects the direction (X-axis, Y-Axis, or both) in which data zooming operations are performed by doZoomIn() and doZoomOut(). |
|
|
ZoomPercentage: This property specifies the percentage of zoom to be performed by doZoomIn() and doZoomOut(). |
|
In addition to these properties and methods, you can also enable data zooming and scrolling via the user interface with the SelectionEnable property. When setSelectionEnable(5) is used, zooming and scrolling functions are enabled. When this mode is used, it allows the user to drag out a rectangle and drill-down on the data within the rectangle area. A single mouse click will back up one data-zoom level or drill-down. Double click will restore the original un-zoomed data state. Note that user interface-based zooming and scrolling is mutually exclusive with selecting chart items. When setSelectionEnable(5) is used, chart objects cannot be selected. |
|
|
When data zooming is enabled with the zoom properties/methods or via the user interface, Perspective will maintain a Zoom Index that keeps track of the number of times a chart has been zoomed in and the state of zooming. As an example, assume ZoomPercentage is set to 10%, and the user clicks ONCE. The chart is now zoomed to 90% of its original values, and the Zoom Index is now 1. Now the user clicks A SECOND TIME. The chart is now zoomed to 80% of its orignal values, and the zoom index now is 2. Or, actually, the zoom index now has TWO entries: one for the first, 90% state, and a second for the second, 80% state. |
|
|
You can keep adding to the zoom index as the user contines to click. Continuing with the example and the same values, assume the user has clicked eight consecutive times. The Zoom index now contains eight items: |
|
|
1. |
First Level: Zoom Factor 90% |
|
2. |
Second Level: Zoom Factor 80% |
|
3. |
Third Level: Zoom Factor 70% |
|
4. |
Fourth Level: Zoom Factor 60% |
|
5. |
Fifth Level: Zoom Factor 50% |
|
6. |
Sixth Level: Zoom Factor 40% |
|
7. |
Seventh Level: Zoom Factor 30% |
|
8. |
Eighth Level: Zoom Factor 20% |
|
Your application can go back and forth in this list. For example, assume you want to switch from the "current" level (the last level the user clicked, the eighth zoom level which currently shows 20% of the original unzooomed state). You could use setZoomIndex(4) to IMMEDIATELY switch to the FOURTH level which had a zoom factor of 60%. You can use setZoomIndex to switch back and forth between any zoom level set. |
|
The following rules govern how missing data points are handled by Perspective for Java: |
|
|
1. |
When a data point is part of a cumulative total (stacked or percent Bar, Line, Area, pie slice), it will be interpreted as 0.0. |
|
2. |
When a data point is used with neighboring points to define a line segment or surface (3D connected, 3D surface, 2D line, 2D area), it will be interpreted as 0.0. |
|
3. |
Otherwise (2D side-by-side bar, 3D riser, 3D floating, 2D and 3D scatter, stock charts, spectral map, histogram), the (missing) point will not be plotted. |
|
If you want examples of HTML, there is a very easy way! Run the TDGChartEditorApplet, move the chart around, etc. and then select "Save" from the menu item. The file that is saved is a text file; you can cut and paste anything from it into HTML (or, for that matter, into Java code). |
|
|
|
|
DATA REQUIREMENTS FOR DIFFERENT CHART TYPES
|
Regardless of the data import method, the data will be interpreted differently based on the selected graph type. In other words, different graph types require different sets of data in order to image the chart properly. The following table shows the data values that are required for each graph type: |
|
|
Graph Type |
Required Data Values per Row (Series) |
|
3D (0-14) |
One |
|
2D (17...54) |
One |
|
Pie (55...60) |
One |
|
XY Scatter (61...62) |
TWO values per marker, X and Y, in that order. |
|
XY Scatter with Labels (63...64) |
THREE values per maker, X, Y and text label, in that order. Each XY point is discreetly labeled. |
|
Polar (65...66) |
TWO values per marker in the following order: X (degree) and Y (distance from the center) |
|
Radar (67...69) |
One |
|
Stock, High, Low, Candle (70) |
FOUR values per marker: Open, High, Low, and Close, in that order. |
|
Stock, High, Low, Volume, Candle (71) |
FIVE values per marker: Open, High, Low, Close and Volume. |
|
Stock, Candle (72) |
FOUR values per marker: Open, High, Low, and Close. A "Candle" financial equity chart |
|
Stock, High, Low (73...75) |
TWO values per marker: High and Low. |
|
Stock, High, Low, Close (76...78) |
THREE values per marker: High, Low, and Close. |
|
Stock, High, Low, Open, Close (79...81) |
FOUR values per marker: Open, High, Low, and Close |
|
Stock, High, Low, Volume (82) |
THREE values per marker: High, Low and Volume |
|
Stock, High, Low, Close, Volume (83) |
FIVE values per marker: Open, High, Low, Close, and Volume |
|
Candle Stock Hi-Lo Open-Close with Volume (84) |
FIVE values per marker: Open, High, Low, Close, and Volume. |
|
Histogram (85...86) |
One |
|
Spectral Map (87) |
One |
|
Stock Hi-Lo Close with Volume (88) |
FOUR values per marker: High, Low, Close, and Volume |
|
Bubble Chart (89) |
Three values per marker -- X, Y, and Z, in that order. |
|
Bubble Chart with Labels (90) |
Four values per marker -- X, Y, Z, and text label, in that order. |
|
Bubble Chart Dual-Axes (91) |
Three values per marker -- X, Y, and Z, in that order. |
|
Bubble Chart with Labels Dual-Axis (92) |
Four values per marker -- X, Y, Z, and text label, in that order. |
|
If your application does not supply the correct number of values for each data point in your chart, you may receive the message "not enough data to draw chart". If you are using the setData() method to define values, make sure you use setDataRangeToExtent() after the last setData() method to apply all data values to the chart. |
|
All 3D chart types require one value for each series/group. The following sample program creates a 3D pyramid chart with two series and four groups: |
|
perspective1.setUseSampleData(false); |
|
|
|
The following sample program creates a vertical bar chart with two series and four groups. |
|
perspective1.setUseSampleData(false); |
|
This data produces a vertical bar chart in the following format: |
|
|
|
The following data is the same as the sample data that was used to define vertical bar chart except a multiple ring pie chart is selected. In pie charts, each series defines a slice in the pie and each group defines a pie: |
|
perspective1.setUseSampleData(false); |
|
When this data is used to define a pie chart, the chart is displayed in the following format: |
|
|
|
XY Scatter Charts require two values per marker -- X and Y, in that order. |
|
perspective1.setUseSampleData(false); |
|
Since there are eight setData() statements in the example code, four markers are drawn in the scatter chart. |
|
|
Data in XY Scatter with Labels Chart
|
XY Scatter Charts with labels require three values per marker -- X and Y and text label, in that order. |
|
perspective1.setUseSampleData(false); |
|
|
|
Polar charts require two values per marker in the following order: X (degree) and Y (distance from center). |
|
perspective1.setUseSampleData(false); |
|
|
|
Radar charts require one per marker to be drawn in the chart. |
|
perspective1.setUseSampleData(false); |
|
|
|
The spectral map requires one value for each cell to be drawn in the map. |
|
perspective1.setUseSampleData(false); |
|
When this data is used to define a spectral map, the chart is displayed in the following format: |
|
|
|
A bubble chart with labels (GraphType 92) requires four values per marker: X, Y, Z, and Text Label: |
||
|
perspective1.setUseSampleData(false); |
||
|
When this data is used to define a bubble chart, the chart is displayed in the following format: |
||
|
|