ScatterPlotTableDataModel: Basic Plots

The main responsibility of a ScatterPlotTableDataModel is to determine which data variables are used in the scatter plot and what role each variable plays. The primary roles are

XVariable

Assigns a plot's X variable, whose values are represented along the horizontal axis.

YVariable

Assigns a plot's Y variable, whose values are represented along the left vertical axis.

Y2Variable

Assigns a second Y variable, whose values are represented along the right vertical axis.

Each of these primary roles are assigned to a PlotVariable. A unique plot element (marker) is produced for each unique X,Y value pair or combination of value pairs when other variable roles are specified.

For example, the following code fragment graphs product sales by assigning the X and Y variable roles to variables named Product and Sales:

 
// Create a data source
   javax.swing.table.TableModel dataTable = <...>;

// Create a data model and attach the data source to it
   ScatterPlotTableDataModel dataModel =
          new ScatterPlotTableDataModel();
   dataModel.setModel(dataTable);
     
// Assign the X and Y variable roles. Assignments
// assume the data source contains a string column
// named Product and a numeric column named Sales.
   dataModel.setXVariable(new PlotVariable("Product"));
   dataModel.setYVariable(new PlotVariable("Sales"));

// Create a ScatterPlot and attach the data model to it
   ScatterPlot scatterPlot = new ScatterPlot();
   scatterPlot.setDataModel(dataModel);

When the model is assigned to a ScatterPlot, one marker is produced for each (X, Y) value pair. If the Y2 role is assigned in the model, a marker is also produced for each (X, Y2) value pair.

ScatterPlotTableDataModel: Plot Markers

The ShapeVariable, SizeVariable, and ColorVariable roles can be used to control the shape, size, and color of the markers in any ScatterPlot. These roles are assigned to Variables, and the assignment would resemble the following:

 
dataModel.setColorVariable(new Variable("CMarker"));

The variables that are assigned these roles must have the appropriate information. For example, a variable that is assigned the Color role must store valid color values.

As an alternative to using a variable role to change plot markers, you can use a plot's ScatterPlotModel to

• assign a MarkerStyle to the markers
• group markers and lines by calling the setStyleBy() method
• hide markers by calling the setMarkerEnabled() method with the argument value false.

ScatterPlotTableDataModel: Labels for Plot Points

To label plot points above or below the plot markers, use the MarkerTopDisplayValueVariable or MarkerBottomDisplayValueVariable roles. Either role can be assigned to a data column that is used to create a Variable in the program code. In the following code fragment, the values from a data column named Gender are used to label plot points above the plot markers:

 
dataModel.setMarkerTopDisplayValueVariable(new Variable("Gender"));

ScatterPlotTableDataModel: Data Groups

To identify data groups according to the values of a ClassificationVariable, assign the GroupVariable role to the appropriate classification variable.

For example, a variable named Gender might be assigned the Group role so that the plot markers reveal which points came from a data row with the Gender value Male, and which came from a row with the Gender value Female. The assignment would resemble the following:

 
dataModel.setGroupVariable(new ClassificationVariable("Gender"));

Markers of different shape and color are used to represent each unique value of the Group variable.

ScatterPlotTableDataModel: High, Low, and Error Values

To use high and low values in a scatter plot, for example, when graphing stock market data or error values, specify multiple data columns on the PlotVariable(s) used in the plot.

• The first specified column is used for the variable's assigned roll.
• The second column is used for the high values.
• The third column is used for the low values.

The PlotVariable constructor allows a null specification for either the high or low values. The constructor also has parameters for specifying value labels.

The following code fragment creates a new PlotVariable that uses variable Dow in the Y variable role, Dow-high for the high values, and Dow-low for the low values.

PlotVariable DowJones=new PlotVariable(
  "Dow"                  // column for Y role
 , "#.00"                // format
 , null                  // informat
 , "Dow Jones Composite" // label
 , "Dow-high"            // highColumnName
 , "Dow High"            // highLabel
 , "Dow-low"             // lowColumnName
 , "Dow Low"             // lowLabel
 );
dataModel.setYVariable(DowJones);

ScatterPlotTableDataModel: Multiple Plots, Same Axes

Multiple Y variables can be plotted against the same X variable by adding the variables to a PlotVariableList, and then assigning that list rather than an individual variable to the Y role.

The following code fragment assigns the X role to variable Product, and the Y role to variables named Actual Sales and Predicted Sales:

 
dataModel.setXVariable(new PlotVariable("Product"));

PlotVariableList multiY=new PlotVariableList(
  new PlotVariable[] {
      new PlotVariable("ActualSales"),
      new PlotVariable("PredictedSales")
  } );

dataModel.setYVariable(multiY);

For this specification, a plot marker is displayed for each product's Actual Sales, and also for each product's Predicted Sales. Markers of different shape and color are used to distinguish each variable's values. To fill the areas between plot lines, use a ScatterPlotModel to call the setFillAreaEnabled() method with the argument value true.

A set of distinct plots can be generated for different X, Y variable pairs by specifying a PlotVariableList for both the X and Y variables as follows:

 
PlotVariableList multiX=new PlotVariableList(
  new PlotVariable[] {
      new PlotVariable("x1"),
      new PlotVariable("x2"),
      new PlotVariable("x3")
  } );

PlotVariableList multiY=new PlotVariableList(
  new PlotVariable[] {
      new PlotVariable("y1"),
      new PlotVariable("y2"),
      new PlotVariable("y3")
  } );

dataModel.setYVariable(multiX);
dataModel.setYVariable(multiY);

In this example, there will be three marker sets: one for (x1, y1), another for (x2, y2), and a third for (x3, y3). Markers of different shape and color are used to distinguish each variable set.

With multiple variables assigned X and/or Y roles, all plot lines use the same set of axes. Therefore, you must be certain that the variables along each axis can be represented by the same value scale. When multiple X variables are specified, there must be a Y variable for each X. One of the Y variables can be assigned the Y2 role rather than the Y role.

ScatterPlotTableDataModel: Multiple Plots in Columns and/or Rows

Separate ScatterPlots can be generated for each value of a ClassificationVariable by assigning either the ColumnVariable or RowVariable role to that variable.

For example, in a plot that shows the correlation between height and weight, a variable named Age might be assigned to the Column role so that a separate plot is generated for each age group. The assignment would resemble the following:

 
dataModel.setColumnVariable(new ClassificationVariable("Age"));

If the Column role is assigned, plots are aligned horizontally by the variable's values. Each column has its own X axis scale, and the plots share the same Y axis and also Y2 axis, when present.

If the Row role is assigned, plots are aligned vertically by the variable's values. Each row has its own Y axis scale and, if the Y2 role is used, Y2 axis scale. The plots share the same X axis.

The Column and Row variable roles can both be assigned to the same graph. In that case, a separate scatter plot is produced for each unique pair of (column, row) values, and the plots are displayed in a grid. For example, when plotting height and weight, a variable named Age might be assigned to the Column role and a variable named Gender might be assigned the Row role. In this case, a separate plot is generated for each gender in each age category.

ScatterPlotTableDataModel: Valid Variable Roles

The following table summarizes the ScatterPlotTableDataModel variable roles and the type of data each role supports.

Variable Role	Class Type	Numeric	String	Multiple Variables
XVariable* Assigns horizontal-axis variable	PlotVariable	Yes	Yes	Yes
YVariable* Assigns left vertical-axis variable	PlotVariable	Yes	Yes	Yes
Y2Variable Assigns right vertical-axis variable	PlotVariable	Yes	Yes	Yes
GroupVariable Associates markers with data groups	ClassificationVariable	No	Yes	No
ColorVariable Assigns marker colors	Variable	Yes	Yes	No
ShapeVariable Assigns marker shapes	Variable	No	Yes	No
SizeVariable Assigns marker sizes	Variable	No	Yes	No
MarkerTopDisplayValueVariable Displays plot-point labels above markers	Variable	Yes	Yes	No
MarkerBottomDisplayValueVariable Displays plot-point labels below markers	Variable	Yes	Yes	No
ColumnVariable Aligns multiple plots in columns	ClassificationVariable	Yes	Yes	Yes
RowVariable Aligns multiple plots in rows	ClassificationVariable	Yes	Yes	Yes
* required variable

ScatterPlotTableDataModel: Behavior

To generate a graph, a ScatterPlot needs data columns for the X and Y variable roles.

If the Y role is not assigned in the program code, a ScatterPlot selects the first numeric column found in the ScatterPlotTableDataModel and uses it as its Y variable. If there is no numeric column in the data, then it selects the first string column.

If the X role is not assigned in the program code, a ScatterPlot selects the first numeric column which is different from Y and uses it as the X variable. If no valid numeric column is found, then it selects the first string column different from Y and uses it as X.

This default behavior occurs only when the X and/or Y role is not assigned. If either role is assigned to a variable that does not exist in the data, the ScatterPlot cannot display a graph.

ScatterPlotTableDataModel: Events

A ScatterPlotTableDataModel fires property change events when

• any of its properties are changed
• any property in a contained model is modified.

For example, if the name property is changed in the PlotVariable that has been assigned the XVariable role, the ScatterPlotTableDataModel fires a ProeprtyChangeEvent stating that the XVariable has changed.

ScatterPlotTableDataModel: Error Handling

When variable roles are assigned, the ScatterPlotTableDataModel does not confirm that the variables exist in the TableModel. Thus, assigning a non-existent data column to a variable role may mean that the ScatterPlot cannot display a graph. For example, if the XVariable role is assigned to a Product column but the TableModel does not contain a Product column, then the ScatterPlot fails to produce a graph.

If the XVariable and YVariable roles are correctly assiged to existing variables but another role is incorrectly assigned, the ScatterPlot displays a graph without the incorrect role. For example, if the XVariable and YVariable roles are correctly assigned but the ColumnVariable role is not, a graph using the X and Y roles is generated, but the Column role is ignored.